From mapbox
Guides AI selection of Mapbox search tools and parameters for geocoding specific addresses/POIs, category-based discovery, and reverse geocoding from coordinates.
npx claudepluginhub mapbox/mapbox-agent-skills --plugin mapboxThis skill uses the workspace's default tool permissions.
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.
Guides implementation of Mapbox Search Box API for address, POI, and location search in apps via discovery questions, product selection, and production best practices.
Automates Google Maps tasks via Rube MCP (Composio): geocode addresses, search places, get directions, compute route matrices, reverse geocode, autocomplete, get place details. Useful for location services in apps.
Integrates Amazon Location Service APIs for maps, geocoding, routing, places search, geofencing, and device tracking in AWS applications.
Share bugs, ideas, or general feedback.
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.
Best for: Specific places, addresses, brands, named locations
Use when query contains:
Don't use for: Generic categories ("coffee shops", "museums")
Best for: Generic place types, categories, plural queries
Use when query contains:
Don't use for: Specific names or brands
Best for: Converting coordinates to addresses, cities, towns, postcodes
Use when:
| 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 |
Three ways to spatially constrain search results:
What it does: Biases results toward a location, but doesn't exclude distant matches
Use when:
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.
What it does: Hard constraint - ONLY returns results within the box
Use when:
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
What it does: Limits results to specific countries
Use when:
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
| 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 |
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
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)
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:
Don't use for:
// BAD
category_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error
// GOOD
search_and_geocode_tool({ q: 'Starbucks' });
// BAD
search_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results
// GOOD
category_search_tool({ category: 'coffee_shop' });
// 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 }
});
// 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 }
});
// 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
// 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
});
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"]
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)Load these for deeper guidance on specific topics:
references/advanced-params.md — poi_category, ETA, format, and language parametersreferences/workflows.md — Common patterns: Near Me, Branded, Geocoding, Category+Area, Reverse, Route-Based, Multilingualreferences/optimization-combining.md — Performance optimization, combining tools, handling no results, category list resource