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.

referencesadvanced-params.md

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

Advanced Parameters Reference

poi_category Parameter

search_and_geocode_tool: Narrow generic searches

{
  "q": "lunch",
  "poi_category": ["restaurant", "cafe"],
  "proximity": { "longitude": -122.4194, "latitude": 37.7749 }
}

When to use:

  • Generic query that could match multiple categories
  • Want to focus search within category
  • User specifies type implicitly

category_search_tool: Use poi_category_exclusions instead

{
  "category": "food_and_drink",
  "poi_category_exclusions": ["bar", "nightclub"]
}

When to use:

  • Broad category but want to exclude subcategories
  • "Restaurants but not fast food"

ETA Parameters (search_and_geocode_tool)

Request estimated time of arrival to results

Parameters:

  • eta_type: Set to "navigation"
  • navigation_profile: "driving" | "walking" | "cycling"
  • origin: Starting coordinates

Use when:

  • User asks "how long to get there?"
  • Sorting by travel time, not distance
  • Need route time, not straight-line distance

Example:

{
  "q": "grocery stores",
  "proximity": { "longitude": -122.4194, "latitude": 37.7749 },
  "eta_type": "navigation",
  "navigation_profile": "driving",
  "origin": { "longitude": -122.4194, "latitude": 37.7749 }
}

Returns: Results with eta (travel time in seconds)

Warning: Requires routing calculation per result (counts toward API quota)

When NOT to use:

  • Just need straight-line distance (use distance_tool offline after search)
  • Budget-conscious (adds API cost)

format Parameter (category_search_tool)

Choose output format:

Format Returns Use When
formatted_text (default) Human-readable text Displaying to user directly
json_string GeoJSON as JSON string Need to parse/process results

Example:

formatted_text:

1. Blue Bottle Coffee
   Address: 66 Mint St, San Francisco, CA
   Coordinates: 37.7825, -122.4052
   Type: poi

json_string:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {"type": "Point", "coordinates": [-122.4052, 37.7825]},
    "properties": {"name": "Blue Bottle Coffee", ...}
  }]
}

Decision:

  • Showing list to user -> formatted_text
  • Plotting on map -> json_string (parse and use coordinates)
  • Further processing -> json_string

language Parameter

ISO language codes (e.g., "en", "es", "fr", "de", "ja", "zh")

Use when:

  • Building multilingual app
  • User's language preference known
  • Need localized names

Example:

{
  "q": "東京タワー",
  "language": "ja"
}
// Returns results in Japanese

Default: English (if not specified)

Tip: Match user's locale for best experience

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.