Writing Effective Search Queries

Semantic search understands natural language, but query quality matters. Learn how to write queries that find exactly what your clients need.

Query Writing Principles

Be Specific and Descriptive

Good Queries

• “Modern kitchen with stainless steel appliances”
• “Family home with large backyard”
• “Open floor plan with natural light”
• “Recently updated bathroom with walk-in shower”
• “Mountain views from master bedroom”
• “Covered front porch with swing”

Less Effective

• “nice house” (too vague)
• “3 bed 2 bath” (use filters instead)
• “cheap home” (use price filters)
• “good neighborhood” (subjective, no features)
• “move-in ready” (ambiguous)

Focus on Features, Not Requirements

Use semantic search for:

• Features: “granite countertops”, “hardwood floors”
• Amenities: “two-car garage”, “fenced yard”
• Characteristics: “open concept”, “vaulted ceilings”
• Details: “recently renovated”, “updated appliances”

Use filters for:

• Quantifiable constraints: bedrooms, bathrooms, price
• Location: city, state, radius
• Status: active, pending, sold
• Property type: residential, land, commercial

Query Examples by Scenario

First-Time Buyers

Focus: Affordability, low maintenance, move-in ready

{
  "query": "updated starter home with modern appliances and low maintenance yard",
  "min_price": 150000,
  "max_price": 250000,
  "min_beds": 2,
  "city": "Jerome"
}

Growing Families

Focus: Space, yard, school proximity

{
  "query": "spacious family home with large backyard and room for kids to play",
  "min_beds": 4,
  "min_baths": 2,
  "city": "Twin Falls"
}

Empty Nesters

Focus: Single-level, low maintenance, accessibility

{
  "query": "single-level home with master suite and easy-care landscaping",
  "max_beds": 3,
  "property_type": "Residential"
}

Luxury Buyers

Focus: High-end finishes, views, unique features

{
  "query": "luxury home with gourmet kitchen, mountain views, and premium finishes throughout",
  "min_price": 600000,
  "city": "Ketchum"
}

Investors

Focus: Rental potential, condition, ROI factors

{
  "query": "rental property with separate units or mother-in-law suite",
  "max_price": 350000,
  "city": "Burley"
}

Land Buyers

Focus: Views, utilities, buildability

{
  "query": "buildable lot with utilities available and mountain views",
  "property_type": "Land",
  "min_price": 50000,
  "max_price": 200000
}

Combining Queries with Filters

Best Practice Pattern

{
  "query": "modern kitchen with island and pantry",
  "min_beds": 3,
  "max_price": 450000,
  "city": "Twin Falls"
}

Why this works:

1. Filters eliminate non-starters (wrong price, beds, city)
2. Query ranks remaining properties by kitchen features
3. Results are both relevant and ranked

Anti-Pattern: All Filters, No Query

{
  "min_beds": 3,
  "max_beds": 4,
  "min_baths": 2,
  "min_price": 200000,
  "max_price": 400000
}

Problem: Results are unranked. You’ll get everything that matches the numbers, but no insight into quality or features.

Anti-Pattern: All Query, No Filters

{
  "query": "3 bedroom 2 bath home in Twin Falls under $400000"
}

Problem: Semantic search isn’t optimized for numbers. Use filters for quantifiable constraints.

Query Length Guidelines

Short Queries (1-3 words)

Use for: Broad feature searches

"granite countertops"
"mountain views"
"fenced yard"

Result: Many matches, requires filtering.

Medium Queries (4-8 words)

Optimal for most searches

"updated kitchen with stainless appliances and island"
"spacious master suite with walk-in closet"

Result: Balanced relevance and recall.

Long Queries (9+ words)

Use for: Very specific requirements

"modern farmhouse with open floor plan, shiplap walls, and covered front porch with rocking chairs"

Result: Fewer but highly relevant matches.

Tip

Start with medium-length queries and adjust based on results. Too few results? Shorten or generalize. Too many irrelevant results? Add more details.

Multi-Feature Queries

Prioritize Features

Order features by importance (most important first):

"mountain views with open floor plan and updated kitchen"

vs.

"updated kitchen with open floor plan and mountain views"

Both work, but the first emphasizes views.

Combining Related Features

Group related features together:

"gourmet kitchen with granite counters, gas range, and island seating"

vs. separate queries for each feature.

Synonyms and Related Terms

The system understands related concepts:

Query Term	Matches
”granite countertops”	granite counters, stone countertops, granite surfaces
”open floor plan”	open concept, flowing layout, great room
”mountain views”	overlooks mountains, views of peaks, mountain vistas
”updated”	renovated, remodeled, modernized
”large yard”	spacious yard, big backyard, expansive lot
”master suite”	primary bedroom, owner’s suite

You don’t need to include all variations — the system finds them.

Avoiding Common Mistakes

Don’t Use Marketing Jargon

Avoid:

"stunning", "amazing", "must-see", "dream home"

Why: These are subjective and appear in most listings.

Instead:

"vaulted ceilings with skylights and panoramic windows"

Don’t Query on Numbers

Avoid:

"4 bedrooms and 2.5 bathrooms"

Why: Use filters for numerical constraints.

Instead:

{
  "query": "split floor plan with master suite separate from other bedrooms",
  "min_beds": 4,
  "min_baths": 2
}

Don’t Mix Multiple Unrelated Features

Avoid:

"granite countertops and mountain views and swimming pool and RV parking"

Why: Too specific, likely zero matches.

Instead: Run separate searches or prioritize features:

"mountain views with RV parking"

Then filter results manually for other features.

Refining Searches

Starting Broad

If you’re not sure what’s available:

{
  "query": "updated kitchen",
  "city": "Burley"
}

Review results, then refine:

{
  "query": "updated kitchen with island and stainless appliances",
  "city": "Burley",
  "min_price": 250000
}

Handling Zero Results

If a search returns nothing:

1. Remove specific details: “granite” → “updated countertops”
2. Broaden location: “Jerome” → radius_miles: 10
3. Relax price range: Expand by 20-30%
4. Check spelling: Typos break matching

Handling Too Many Results

If results are overwhelming:

1. Add more specific features: “kitchen” → “kitchen with island and pantry”
2. Tighten filters: Narrow price range, increase bedroom minimum
3. Reduce search radius: 10 miles → 5 miles

Testing Your Queries

Check Similarity Scores

Good queries produce scores ≥ 0.6 for top results. If all scores are < 0.5, your query may be too specific or use uncommon terms.

Review Matched Text

The API returns matched_text snippets showing why properties matched. Review these to understand what the system found.

Example:

{
  "query": "mountain views",
  "matched_text": "...enjoy stunning panoramic views of the Sawtooth Mountains from the living room and deck..."
}

If matched text doesn’t align with your intent, refine the query.

Related

• Search API Reference — Endpoint specifications
• Search Quality Scores — Understanding similarity scores
• Effective Property Search — General search strategies