---
name: mapbox-location-grounding
description: Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data
---

# mapbox-location-grounding

Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data

# mapbox-location-groundingby mapbox
Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data

`npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-location-grounding`Download ZIPGitHub

## Mapbox Location Grounding Skill

Teaches AI assistants how to ground location-aware responses in live Mapbox data by composing MCP tools into a structured, cited answer. Use this instead of relying on training data for place names, POIs, ratings, or travel times — which are stale and prone to hallucination.

## When to Use Grounding

Ground responses when the user asks about:

* "What's near [location]?" or "What's around [coordinate]?"

* "Describe this neighborhood / area"

* "Find [category] within walking/driving distance"

* "What can I do near [address]?"

* "How long does it take to get from A to B?"

* "What's within a 10-minute walk of here?"

* "How far is it between these locations?"

* Real estate, travel, mobility, or local discovery use cases

* Any question where place accuracy, recency, or travel time matters

Never answer location questions from training data alone. Always retrieve live data.

## Grounding Tool Composition

### Preferred: single tool call

If `ground_location_tool` is available, use it — it handles reverse geocoding, POI search, place details enrichment, isochrone, and a static map image in one call:

```
`ground_location_tool(
longitude, latitude,
query: "restaurant", // optional — category or subcategory of nearby places to find
profile: "mapbox/walking", // optional — travel profile for isochrone
contours_minutes: [5, 10, 15]
)
`
```

Returns:

* Neighborhood/place name from reverse geocoding

* Nearby POIs with distances, ratings, price levels, and popularity (when available)

* Travel-time reachability from isochrone

* A static map image for visual context

* Citations for all data sources

Do not call `reverse_geocode_tool`, `category_search_tool`, `place_details_tool`, or `isochrone_tool` separately — they are already composed inside this tool.

### Query parameter

The `query` parameter accepts category or subcategory terms — not attribute preferences:

* Supported: `"restaurant"`, `"coffee"`, `"park"`, `"Italian restaurant"`, `"EV charging station"`

* Not supported: `"family-friendly"`, `"fast charging"`, `"outdoor seating"` — these are not filterable attributes in Mapbox data

To help users find places matching a preference (e.g. "family-friendly"), search by category (`"restaurant"`) and use the returned rating and price data to inform the recommendation.

### Fallback: manual composition

If `ground_location_tool` is not available, build the grounded response by composing these tools in order:

Step 1 — Establish place context

```
`reverse_geocode_tool(longitude, latitude, types: "neighborhood,locality,place")
`
```

Returns: neighborhood, city, region, country. This is the anchor for the response.

Step 2 — Retrieve nearby POIs
For specific names or brands:

```
`search_and_geocode_tool(query, proximity: {longitude, latitude}, limit: 10)
`
```

For generic categories:

```
`category_search_tool(category, proximity: {longitude, latitude}, limit: 10)
`
```

Step 3 — Enrich POIs with ratings and price (optional but high-value)
For each POI with a `mapbox_id`, call in parallel:

```
`place_details_tool(mapbox_id, attribute_sets: ["visit"])
`
```

Returns: rating, price level, popularity, and opening hours per place.

Step 4 — Add travel-time context (optional but high-value)

```
`isochrone_tool(
coordinates: {longitude, latitude},
profile: "mapbox/walking", // or "mapbox/driving", "mapbox/cycling", "mapbox/driving-traffic"
contours_minutes: [5, 10, 15]
)
`
```

Returns a polygon showing what's reachable within each time threshold.

Step 5 — Visual grounding (optional)

```
`static_map_image_tool(longitude, latitude, zoom: 14)
`
```

Returns a map image that can be included in the response for visual context.

## Grounded Response Structure

Always structure grounded responses with explicit citations:

```
`Place: [neighborhood, city from reverse_geocode]
Nearby [category]: [list from search/category tool, with names, ratings, prices, and distances]
Travel context: [X min walk / Y min drive from isochrone]
Sources: Mapbox Search, Mapbox Directions (live data)
`
```

Example grounded response:

SoMa, San Francisco, CA (live Mapbox data)

Restaurants within walking distance:

* Bix Restaurant $$ ★8.4 — 56 Gold St (180m)

* The Bird $ ★7.9 — 115 New Montgomery St (320m)

* Oren's Hummus $$ ★8.1 — 131 Townsend St (510m)

Reachable by walking: 5 min, 10 min, 15 min

Sources: Mapbox Geocoding API, Mapbox Search API, Mapbox Place Details API, Mapbox Isochrone API, Mapbox Static Images API

## Routing Grounding

For questions about travel between two locations, use `directions_tool`. For questions about reachable area, use `isochrone_tool`. For comparing travel times across multiple locations, use `matrix_tool`.

### Point-to-point travel time and distance

"How long does it take to drive from Pike Place Market to Capitol Hill?"
"What's the fastest route from the hotel to the airport?"

```
`directions_tool(
waypoints: [{longitude, latitude}, {longitude, latitude}],
profile: "mapbox/driving-traffic" // live traffic; or "mapbox/walking", "mapbox/cycling", "mapbox/driving"
)
`
```

Returns: duration (with live traffic), distance, turn-by-turn steps, and an encoded polyline for map rendering. Supports up to 25 waypoints for multi-stop routes.

### Area reachability ("within X minutes")

"What's reachable within a 10-minute walk?"
"Show me what I can reach in 15 minutes by car from here"

```
`isochrone_tool(
coordinates: {longitude, latitude},
profile: "mapbox/walking",
contours_minutes: [5, 10, 15]
)
`
```

Returns a polygon showing the area reachable within each time threshold. Combine with `category_search_tool` or `ground_location_tool` to answer "what restaurants are within a 10-minute walk?" — use the isochrone to define the boundary, then search within it.

### Multi-location travel time matrix

"Which of these three offices is closest to my location?"
"What are travel times from this warehouse to each of our delivery zones?"
"Compare commute times to multiple locations"

Use `matrix_tool` — do NOT call `directions_tool` separately for each pair. Matrix batches all pairs in a single API call.

```
`matrix_tool(
sources: [{longitude, latitude}, ...],
destinations: [{longitude, latitude}, ...],
profile: "mapbox/driving-traffic"
)
`
```

Returns a matrix of durations and distances between every source/destination pair. Rank results by duration to find the nearest location. One `matrix_tool` call replaces N separate `directions_tool` calls.

### Proximity search with routing context

For "find [category] within X minutes of [location]":

* Geocode the origin if needed: `search_and_geocode_tool(address)`

* Get the reachable area: `isochrone_tool(coordinates, profile, contours_minutes)`

* Search for POIs: `ground_location_tool(longitude, latitude, query: "category")` — the isochrone
contours tell the user what's within each time band

Or more directly: `ground_location_tool` returns both nearby POIs and isochrone reachability in one
call, which covers most proximity + routing use cases without additional composition.

### Example routing response

Pike Place Market → Capitol Hill, Seattle

By car (with traffic): 12 min, 3.2 km via Pine St
By walking: 28 min, 2.1 km
By cycling: 14 min, 2.3 km

Source: Mapbox Directions API (live traffic)

## What Mapbox Grounding Offers vs. Training Data

Training DataMapbox GroundingPOI accuracyStale, hallucinatedLive, verifiedRatings/priceOften wrongLive via Place DetailsBusiness hoursOften wrongLive via Place DetailsTravel timesEstimatedLive traffic via DirectionsReachable areaNot availableIsochrone polygonsMulti-stop routingNot availableUp to 25 waypointsNew placesMissingIndexedMap imageNoneInline static mapCitationsNoneTool + API source

## Important Limitations

* Attribute filtering (family-friendly, outdoor seating, fast charging) is not supported by the category search API. Use category terms and let rating/price data inform preference-based recommendations.

* POI coverage varies by region. If search returns few results, say so rather than padding with guesses.

* Coordinates required for proximity search — if the user provides an address, geocode it first with `search_and_geocode_tool` before running category search.

## Anti-Patterns to Avoid

* Answering "what's near X?" from training data without calling search tools

* Estimating travel times without calling `directions_tool` or `isochrone_tool`

* Hallucinating business names, hours, or ratings

* Calling `reverse_geocode_tool` + `category_search_tool` + `place_details_tool` separately when `ground_location_tool` is available

* Using attribute terms like "family-friendly" as the query parameter — use the category instead

* Returning raw tool output without synthesizing into a readable response

* Omitting citations — always indicate the response is grounded in live Mapbox data

## More skills from mapbox
mapbox-android-patternsby mapboxOfficial integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and…mapbox-cartographyby mapboxExpert guidance on map design principles, color theory, visual hierarchy, typography, and cartographic best practices for creating effective and beautiful maps…mapbox-data-visualization-patternsby mapboxPatterns for visualizing data on maps including choropleth maps, heat maps, 3D visualizations, data-driven styling, and animated data. Covers layer types,…mapbox-geospatial-operationsby mapboxExpert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needsmapbox-google-maps-migrationby mapboxMigration guide for developers moving from Google Maps Platform to Mapbox GL JS, covering API equivalents, pattern translations, and key differencesmapbox-ios-patternsby mapboxOfficial integration patterns for Mapbox Maps SDK on iOS. Covers installation, adding markers, user location, custom data, styles, camera control, and…mapbox-maplibre-migrationby mapboxGuide for migrating from MapLibre GL JS to Mapbox GL JS, covering API compatibility, token setup, style configuration, and the benefits of Mapbox's official…mapbox-mcp-devkit-patternsby mapboxIntegration patterns for Mapbox MCP DevKit Server in AI coding assistants. Covers setup, style management, token management, validation workflows, and…

---

**Source**: https://github.com/mapbox/mapbox-agent-skills/tree/HEAD/skills/mapbox-location-grounding
**Author**: mapbox
**Discovered via**: mcpservers.org