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. searchandgeocode_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. categorysearchtool

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. reversegeocodetool

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"	searchandgeocodetool	Specific brand name
"Find coffee shops nearby"

categorysearch_tool | Generic category, plural | | "What's at 37.7749, -122.4194?" | reversegeocodetool | Coordinates to address | | "Empire State Building" | searchandgeocode_tool | Specific named POI | | "hotels in downtown Seattle" | categorysearchtool | Generic type + location | | "Target store locations" | searchandgeocode_tool | Brand name (even plural) | | "any restaurant near me" | categorysearchtool | Generic + "any" phrase | | "123 Main St, Boston, MA" | searchandgeocode_tool | Specific address | | "electric vehicle chargers" | categorysearchtool | Industry category | | "McDonald's" | searchandgeocode_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:

CODEBLOCK0

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:

CODEBLOCK1

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:

CODEBLOCK2

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

categorysearchtool 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 (searchandgeocode_tool)

Filter by feature type:

Type	What It Includes	Use When
INLINECODE3	Points of interest (businesses, landmarks)	Looking for POIs, not addresses
INLINECODE4

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:

CODEBLOCK3

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

autocomplete Parameter (searchandgeocodetool)

What it does: Enables partial/fuzzy matching

Setting	Behavior	Use When
INLINECODE11	Matches partial words, typos	User typing in real-time
INLINECODE12 (default)

Exact matching | Final query, not autocomplete |

Example:

CODEBLOCK4

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

CODEBLOCK5

Don't: Use searchandgeocode for generic categories

CODEBLOCK6

Don't: Forget proximity for local searches

CODEBLOCK7

Don't: Use bbox when you mean proximity

CODEBLOCK8

Don't: Request ETA unnecessarily

CODEBLOCK9

Don't: Set limit too high for UI display

CODEBLOCK10

Quick Reference

Tool Selection Flowchart

CODEBLOCK11

Essential Parameters Checklist

For local searches, ALWAYS set:

• - proximity (or bbox if strict boundary needed)

For category searches, consider:

• - limit (match UI needs)
• INLINECODE15 (json_string if plotting on map)

For disambiguation, use:

• - country (when geographic context matters)
• INLINECODE17 (when feature type matters)

For travel-time ranking:

• - eta_type, navigation_profile, origin (costs API quota)

Common Mistakes

1. 1. Forgetting proximity -> Results are global/IP-based
2. Using wrong tool -> categorysearch for "Starbucks" (use searchandgeocode)
3. Invalid category -> Check categorylist first
4. Bbox too small -> No results; use proximity instead
5. Requesting ETA unnecessarily -> Adds API cost
6. Limit too high for UI -> Overwhelming user
7. 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