mapbox-search-patterns

SKILL.md

Mapbox Search Patterns Skill

Expert guidance for AI assistants on using Mapbox search tools effectively. Covers tool selection, parameter optimization, and best practices for geocoding, POI search, and location discovery.

Available Search Tools

1. search_and_geocode_tool

Best for: Specific places, addresses, brands, named locations

Use when query contains:

Specific names: "Starbucks on 5th Avenue", "Empire State Building"

Brand names: "McDonald's", "Whole Foods"

Addresses: "123 Main Street, Seattle", "1 Times Square"

Chain stores: "Target"

Cities/places: "San Francisco", "Portland"

Don't use for: Generic categories ("coffee shops", "museums")
2. category_search_tool

Best for: Generic place types, categories, plural queries

Use when query contains:

Generic types: "coffee shops", "restaurants", "gas stations"

Plural forms: "museums", "hotels", "parks"

Is-a phrases: "any coffee shop", "all restaurants", "nearby pharmacies"

Industry terms: "electric vehicle chargers", "ATMs"

Don't use for: Specific names or brands

3. reverse_geocode_tool

Best for: Converting coordinates to addresses, cities, towns, postcodes

Use when:

Have GPS coordinates, need human-readable address

Need to identify what's at a specific location

Converting user location to address

Tool Selection Decision Matrix

User Query
Tool
Reasoning

"Find Starbucks on Main Street"
search_and_geocode_tool
Specific brand name

"Find coffee shops nearby"
category_search_tool
Generic category, plural

"What's at 37.7749, -122.4194?"
reverse_geocode_tool
Coordinates to address

"Empire State Building"
search_and_geocode_tool
Specific named POI

"hotels in downtown Seattle"
category_search_tool
Generic type + location

"Target store locations"
search_and_geocode_tool
Brand name (even plural)

"any restaurant near me"
category_search_tool
Generic + "any" phrase

"123 Main St, Boston, MA"
search_and_geocode_tool
Specific address

"electric vehicle chargers"
category_search_tool
Industry category

"McDonald's"
search_and_geocode_tool
Brand name

Parameter Guidance

Proximity vs Bbox vs Country

Three ways to spatially constrain search results:

1. proximity (STRONGLY RECOMMENDED)

What it does: Biases results toward a location, but doesn't exclude distant matches

Use when:

User says "near me", "nearby", "close to"

Have a reference point but want some flexibility

Want results sorted by relevance to a point

Example:

{
  "q": "pizza",
  "proximity": {
    "longitude": -122.4194,
    "latitude": 37.7749
  }
}

Why this works: API returns SF pizza places first, but might include famous NYC pizzerias if highly relevant

Critical: Always set proximity when you have a reference location! Without it, results are IP-based or global.

2. bbox (Bounding Box)

What it does: Hard constraint - ONLY returns results within the box

Use when:

User specifies an area: "in downtown", "within this neighborhood"

Have a defined service area

Need to guarantee results are within bounds

Example:

{
  "q": "hotel",
  "bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}

Why this works: Guarantees all hotels are within SF's downtown area

Watch out: Too small = no results; too large = irrelevant results

3. country

What it does: Limits results to specific countries

Use when:

User specifies country: "restaurants in France"

Building country-specific features

Need to respect regional boundaries

Or it is otherwise clear they want results within a specific country

Example:

{
  "q": "Paris",
  "country": ["FR"] // ISO 3166 alpha-2 codes
}

Why this works: Finds Paris, France (not Paris, Texas)

Can combine: proximity + country + bbox or any combination of the three

Decision Matrix: Spatial Filters

Scenario
Use
Why

"Find coffee near me"
proximity
Bias toward user location

"Coffee shops in downtown Seattle"
proximity + bbox
Center on downtown, limit to area

"Hotels in France"
country
Hard country boundary

"Best pizza in San Francisco"
proximity + country ["US"]
Bias to SF, limit to US

"Gas stations along this route"
bbox around route
Hard constraint to route corridor

"Restaurants within 5 miles"
proximity (then filter by distance)
Bias nearby, filter results

Setting limit Parameter

category_search_tool only (1-25, default 10)

Use Case
Limit
Reasoning

Quick suggestions
5
Fast, focused results

Standard list
10
Default, good balance

Comprehensive search
25
Maximum allowed

Map visualization
25
Show all nearby options

Dropdown/autocomplete
5
Don't overwhelm UI

Performance tip: Lower limits = faster responses

types Parameter (search_and_geocode_tool)

Filter by feature type:

Type
What It Includes
Use When

poi
Points of interest (businesses, landmarks)
Looking for POIs, not addresses

address
Street addresses
Need specific address

place
Cities, neighborhoods, regions
Looking for area/region

street
Street names without numbers
Need street, not specific address

postcode
Postal codes
Searching by ZIP/postal code

district
Districts, neighborhoods
Area-based search

locality
Towns, villages
Municipality search

country
Country names
Country-level search

Example combinations:

// Only POIs and addresses, no cities
{"q": "Paris", "types": ["poi", "address"]}
// Returns Paris Hotel, Paris Street, not Paris, France

// Only places (cities)
{"q": "Paris", "types": ["place"]}
// Returns Paris, France; Paris, Texas; etc.

Default behavior: All types included (usually what you want)

auto_complete Parameter (search_and_geocode_tool)

What it does: Enables partial/fuzzy matching

Setting
Behavior
Use When

true
Matches partial words, typos
User typing in real-time

false (default)
Exact matching
Final query, not autocomplete

Example:

// User types "starb"
{ "q": "starb", "auto_complete": true }
// Returns: Starbucks, Starboard Tavern, etc.

Use for:

Search-as-you-type interfaces

Handling typos ("mcdonalds" -> McDonald's)

Incomplete queries

Don't use for:

Final/submitted queries (less precise)

When you need exact matches

Anti-Patterns to Avoid

Don't: Use category_search for brands

// BAD
category_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error

// GOOD
search_and_geocode_tool({ q: 'Starbucks' });

Don't: Use search_and_geocode for generic categories

// BAD
search_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results

// GOOD
category_search_tool({ category: 'coffee_shop' });

Don't: Forget proximity for local searches

// BAD - Results may be anywhere globally
category_search_tool({ category: 'restaurant' });

// GOOD - Biased to user location
category_search_tool({
  category: 'restaurant',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

Don't: Use bbox when you mean proximity

// BAD - Hard boundary may exclude good nearby results
search_and_geocode_tool({
  q: 'pizza',
  bbox: [-122.42, 37.77, -122.41, 37.78] // Tiny box
});

// GOOD - Bias toward point, but flexible
search_and_geocode_tool({
  q: 'pizza',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

Don't: Request ETA unnecessarily

// BAD - Costs API quota for routing calculations
search_and_geocode_tool({
  q: 'museums',
  eta_type: 'navigation',
  navigation_profile: 'driving'
});
// User didn't ask for travel time!

// GOOD - Only add ETA when needed
search_and_geocode_tool({ q: 'museums' });
// If user asks "how long to get there?", then add ETA

Don't: Set limit too high for UI display

// BAD - Overwhelming for simple dropdown
category_search_tool({
  category: 'restaurant',
  limit: 25
});
// Returns 25 restaurants for a 5-item dropdown

// GOOD - Match UI needs
category_search_tool({
  category: 'restaurant',
  limit: 5
});

Quick Reference

Tool Selection Flowchart

User query contains...

-> Specific name/brand (Starbucks, Empire State Building)
  -> search_and_geocode_tool

-> Generic category/plural (coffee shops, museums, any restaurant)
  -> category_search_tool

-> Coordinates -> Address
  -> reverse_geocode_tool

-> Address -> Coordinates
  -> search_and_geocode_tool with types: ["address"]

Essential Parameters Checklist

For local searches, ALWAYS set:

proximity (or bbox if strict boundary needed)

For category searches, consider:

limit (match UI needs)

format (json_string if plotting on map)

For disambiguation, use:

country (when geographic context matters)

types (when feature type matters)

For travel-time ranking:

eta_type, navigation_profile, origin (costs API quota)

Common Mistakes

Forgetting proximity -> Results are global/IP-based

Using wrong tool -> category_search for "Starbucks" (use search_and_geocode)

Invalid category -> Check category_list first

Bbox too small -> No results; use proximity instead

Requesting ETA unnecessarily -> Adds API cost

Limit too high for UI -> Overwhelming user

Not filtering types -> Get cities when you want POIs

Reference Files

Load these for deeper guidance on specific topics:

references/advanced-params.md — poi_category, ETA, format, and language parameters

references/workflows.md — Common patterns: Near Me, Branded, Geocoding, Category+Area, Reverse, Route-Based, Multilingual

references/optimization-combining.md — Performance optimization, combining tools, handling no results, category list resource

1d:["$