Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
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
// BADcategory_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error// GOODsearch_and_geocode_tool({ q: 'Starbucks' });
Don't: Use search_and_geocode for generic categories
// BADsearch_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results// GOODcategory_search_tool({ category: 'coffee_shop' });
Don't: Forget proximity for local searches
// BAD - Results may be anywhere globallycategory_search_tool({ category: 'restaurant' });
// GOOD - Biased to user locationcategory_search_tool({
category: 'restaurant',
proximity: { longitude: -122.4194, latitude: 37.7749 }
});
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.
// BAD — limit=1 without proximity can resolve "Lincoln Memorial" to Illinoisfetch(`https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json?access_token=${token}&limit=1`);
// GOOD — bias to map center (and optional bbox)fetch(
`https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json` +
`?access_token=${token}&proximity=-77.0369,38.9072&bbox=-77.15,38.79,-76.90,38.99&limit=1`
);
Also debounce search inputs (clearTimeout + setTimeout) so every keystroke does not fire a geocode.
Don't: Use bbox when you mean proximity
// BAD - Hard boundary may exclude good nearby resultssearch_and_geocode_tool({
q: 'pizza',
bbox: [-122.42, 37.77, -122.41, 37.78] // Tiny box
});
// GOOD - Bias toward point, but flexiblesearch_and_geocode_tool({
q: 'pizza',
proximity: { longitude: -122.4194, latitude: 37.7749 }
});
Don't: Request ETA unnecessarily
// BAD - Costs API quota for routing calculationssearch_and_geocode_tool({
q: 'museums',
eta_type: 'navigation',
navigation_profile: 'driving'
});
// User didn't ask for travel time!// GOOD - Only add ETA when neededsearch_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 dropdowncategory_search_tool({
category: 'restaurant',
limit: 25
});
// Returns 25 restaurants for a 5-item dropdown// GOOD - Match UI needscategory_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 (or wrong state for ambiguous memorial/park names)
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
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
