mapbox-search-patterns_skill

Overview

This skill provides expert guidance on choosing the right Mapbox search tool and tuning parameters for geocoding, POI search, and location discovery. It helps assistants decide between search_and_geocode, category_search, and reverse_geocode, and recommends spatial filters, result formats, and other options for accurate, performant results. The guidance focuses on practical patterns and common pitfalls.

How this skill works

The skill inspects user intent and query structure to pick the appropriate Mapbox tool: brand/address/named POI → search_and_geocode, generic categories/plural queries → category_search, and coordinates → reverse_geocode. It then recommends spatial constraints (proximity, bbox, country), result types, limits, language, and optional ETA parameters. The guidance also provides concrete request patterns and parameter examples to implement each workflow reliably.

When to use it

• search_and_geocode_tool for specific names, addresses, brands, or named landmarks
• category_search_tool for generic place types, plural queries, and industry categories
• reverse_geocode_tool when converting coordinates to human-readable addresses
• Use proximity when user location or a reference point exists and results should be biased nearby
• Use bbox when you must enforce a strict geographic boundary, like a neighborhood or route corridor

Best practices

• Always set proximity when you have a reference location — it biases results toward relevance without excluding matches
• Combine filters when useful: proximity+country to bias and restrict, bbox to guarantee containment when required
• Use types and poi_category to narrow ambiguous queries (e.g., types:['address'] for geocoding addresses)
• Limit results appropriately: 5 for quick suggestions, 10 for standard lists, 25 for comprehensive maps; lower limits improve performance
• Use auto_complete=true only for typing/AS-you-type interfaces; disable for final queries to avoid fuzzy matches
• Use ETA features only when you need travel time; it increases API cost because routing is computed per result

Example use cases

• "Find coffee shops near me" → category_search with proximity and limit 10
• "Find all Starbucks in Seattle" → search_and_geocode with q:'Starbucks', Seattle proximity or Seattle bbox
• "What are the coordinates of 1600 Pennsylvania Ave?" → search_and_geocode with types:['address'] and country:['US']
• "What's at 37.7749, -122.4194?" → reverse_geocode for address/place/postcode as needed
• "Find gas stations along my route" → get route geometry, build bbox around route, category_search for gas stations, then filter by distance to route