skilld
All skills
mapbox avatar

/mapbox-search-patterns

@f5ae7de official
by mapboxmapbox/mapbox-agent-skills80 stars
17

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

Ask your Agent

Use this Skill: https://skilld.dev/gh/mapbox/mapbox-agent-skills/mapbox-search-patterns

This session only. Nothing lands on disk.

referencesworkflows.md

≈652 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Common Patterns and Workflows

Pattern 1: "Near Me" Search

User: "Find coffee shops near me"

Optimal approach:

1. Get user's location (from app/browser)
2. Use category_search_tool:
   - category: "coffee_shop"
   - proximity: user's coordinates
   - limit: 10

Why: Category tool for generic "coffee shops", proximity for "near me"

Pattern 2: Branded Chain Lookup

User: "Find all Starbucks in Seattle"

Optimal approach:

1. Use search_and_geocode_tool:
   - q: "Starbucks"
   - proximity: Seattle coordinates
   - country: ["US"]
2. Or if need strict boundary:
   - bbox: Seattle city bounds

Why: Brand name = search_and_geocode_tool; proximity biases to Seattle

Pattern 3: Address Geocoding

User: "What are the coordinates of 1600 Pennsylvania Ave?"

Optimal approach:

Use search_and_geocode_tool:
- q: "1600 Pennsylvania Ave, Washington DC"
- types: ["address"]  // Focus on addresses
- country: ["US"]     // Narrow to US

Why: Specific address with country context for disambiguation

Pattern 4: Category Search with Area Restriction

User: "Show me all hotels in downtown Portland"

Optimal approach:

1. Geocode "downtown Portland" → get center point
2. Define downtown bbox (or use 1-2 mile radius)
3. Use category_search_tool:
   - category: "hotel"
   - bbox: downtown bounds (or proximity + filter by distance)
   - limit: 25  // Get comprehensive list

Why: Category for "hotels", bbox for "in downtown" hard boundary

Pattern 5: Reverse Geocoding

User: "What's at these GPS coordinates?"

Optimal approach:

Use reverse_geocode_tool:
- longitude: -122.4194
- latitude: 37.7749
- types: ["address"]  // Get address (can also use place, locality, postcode, etc.)

Why: Coordinates → address is exactly what reverse geocoding does

Pattern 6: Route-Based Search

User: "Find gas stations along my route"

Optimal approach:

1. Get route geometry from directions_tool
2. Create bbox around route (use bounding_box_tool)
3. Use category_search_tool:
   - category: "gas_station"
   - bbox: route bounding box
4. Filter results to those within X meters of route (use distance_tool)

Why: Bbox for rough filter, then distance calculation for precision

Pattern 7: Multilingual POI Search

User: "Find ramen shops" (user locale: ja)

Optimal approach:

Use category_search_tool:
- category: "ramen_restaurant" (or "restaurant")
- language: "ja"
- proximity: user location

Why: Returns Japanese names/addresses for better UX

Source: SKILL.md on GitHub

Third-party checks

No alerts17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The Mapbox Search Patterns skill is a comprehensive documentation package providing guidance on using Mapbox search tools. It contains only instructional content, best practices, and evaluation examples, with no executable code or security risks identified.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer6mo

    1 file scanned · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at f5ae7de. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 9 hours ago.

Activeupdated 2 months ago

Topics

  • mapbox
  • geocoding
  • search
  • poi
  • location-discovery
  • reverse-geocoding
  • spatial-search
  • api-patterns

README badge

README badge for mapbox/mapbox-agent-skills/mapbox-search-patterns

What it does

Provides decision guidance for choosing between Mapbox's search_and_geocode_tool, category_search_tool, and reverse_geocode_tool based on query type, plus parameter optimization for proximity, bbox, country filtering, and result limits. Use this skill when building location search features to select the right tool and avoid common mistakes like forgetting proximity or using category search for brand names.

Generated from the current SKILL.md.

Frequently asked

Should I use search_and_geocode_tool or category_search_tool for a brand like Starbucks?
Use search_and_geocode_tool for brand names. category_search_tool is for generic place types like 'coffee shops' or 'restaurants', not specific brands.
When should I use proximity vs bbox for spatial filtering?
Use proximity to bias results toward a location while allowing flexibility (best for 'near me' queries). Use bbox for a hard boundary when results must stay within a defined area, like a specific neighborhood.
Do I need to set proximity for local searches?
Yes. Without proximity, bbox, or country constraints, results are determined by IP-based location or global relevance, not the user's actual location.
What does the limit parameter do and when should I use it?
limit controls how many results to return (1-25, default 10) and only applies to category_search_tool. Use lower limits (5) for UI dropdowns and higher limits (25) for comprehensive lists or maps.
Should I request ETA (travel time) in every search?
No. ETA adds API cost and should only be included when the user explicitly asks about travel time or distance. Requesting it unnecessarily wastes quota.

Generated from the current SKILL.md. These answers refresh after source changes.