Mapbox Search Patterns

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

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

Setting limit Parameter

category_search_tool only (1-25, default 10)

Performance tip: Lower limits = faster responses

types Parameter (search_and_geocode_tool)

Filter by feature type:

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

Example:

<!-- cspell:disable -->

// 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)

<!-- cspell:enable -->

• Incomplete queries

Don't use for:

• Final/submitted queries (less precise)
• When you need exact matches