Expert guidance on choosing the right Mapbox search tool and parameters for geocoding, POI search, and location discovery

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: 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: 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: 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: 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: <! cspell:disable 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 Anti Patterns to Avoid Don't: Use category search for brands Don't: Use search and geocode for generic categories Don't: Forget proximity for local searches Don't: Geocode ambiguous place names without proximity (REST too) This applies to Mapbox Geocoding API v5 / Search Box in browser apps — not only MCP tools. Also debounce search inputs ( clearTimeout + setTimeout ) so every keystroke does not fire a geocode. Don't: Use bbox when you mean proximity Don't: Request ETA unnecessarily Don't: Set limit too high for UI display Quick Reference Tool Selection Flowchart 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 1. Forgetting proximity Results are global/IP based (or wrong state for ambiguous memorial/park names) 2. Using wrong tool category search for "Starbucks" (use search and geocode) 3. Invalid category Check category list 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 8. No debounce on typeahead Quota burn and racy UI 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

mapbox-search-patterns