mapbox-location-grounding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mapbox Location Grounding Skill

Mapbox位置锚定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.

该Skill指导AI助手通过组合MCP工具生成结构化、带引用的答案，从而基于实时Mapbox数据生成位置感知响应。无需依赖训练数据获取地名、POI（兴趣点）、评分或行程时间——这些数据既过时又容易产生幻觉。

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.

当用户询问以下问题时，需基于实时数据生成响应：

"[地点]附近有什么？"或"[坐标]周边有什么？"
"描述这个街区/区域"
"在步行/驾车范围内寻找[类别]"
"[地址]附近可以做什么？"
"从A到B需要多长时间？"
"这里步行10分钟范围内有什么？"
"这些地点之间距离有多远？"
房地产、旅游、出行或本地探索相关场景
任何对地点准确性、时效性或行程时间有要求的问题

绝对不要仅依靠训练数据回答位置相关问题。务必获取实时数据。

Grounding Tool Composition

锚定工具组合

Preferred: single tool call

优先方案：单次工具调用

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.

如果

ground_location_tool

可用，请使用它——它可在一次调用中处理反向地理编码、POI搜索、地点详情补充、等时线以及静态地图图像：

ground_location_tool(
  longitude, latitude,
  query: "restaurant",   // 可选——要查找的周边地点类别或子类别
  profile: "mapbox/walking",    // 可选——等时线的出行模式
  contours_minutes: [5, 10, 15]
)

返回内容：

来自反向地理编码的街区/地点名称
包含距离、评分、价格等级和热门程度（如有）的周边POI
来自等时线的行程时间可达范围
用于视觉参考的静态地图图像
所有数据源的引用

请勿单独调用

reverse_geocode_tool

、

category_search_tool

、

place_details_tool

或

isochrone_tool

——这些工具已整合在

ground_location_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.

query

参数接受类别或子类别术语——不接受属性偏好：

支持：

"restaurant"

"coffee"

"park"

"Italian restaurant"

"EV charging station"

不支持：
```
"family-friendly"
```
,
```
"fast charging"
```
,
```
"outdoor seating"
```
——这些不属于Mapbox数据中可过滤的属性

若要帮助用户找到符合偏好的地点（例如"适合家庭"），请按类别搜索（如

"restaurant"

），并使用返回的评分和价格数据给出推荐。

Fallback: manual composition

备用方案：手动组合

ground_location_tool

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

如果

ground_location_tool

不可用，请按以下顺序组合这些工具来构建基于实时数据的响应：

Step 1 — Establish place context

步骤1——建立地点上下文

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

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

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

返回：街区、城市、地区、国家。这是响应的锚点。

Step 2 — Retrieve nearby POIs

步骤2——获取周边POI

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)

针对特定名称或品牌：

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

针对通用类别：

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

Step 3 — Enrich POIs with ratings and price (optional but high-value)

步骤3——为POI补充评分和价格（可选但价值高）

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.

对每个带有

mapbox_id

的POI，并行调用：

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

返回：每个地点的评分、价格等级、热门程度和营业时间。

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

步骤4——添加行程时间上下文（可选但价值高）

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.

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

返回一个多边形，展示每个时间阈值内可到达的区域。

Step 5 — Visual grounding (optional)

步骤5——视觉锚定（可选）

static_map_image_tool(longitude, latitude, zoom: 14)

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

static_map_image_tool(longitude, latitude, zoom: 14)

返回可包含在响应中的地图图像，用于视觉参考。

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

务必构建带有明确引用的响应：

地点：[反向地理编码得到的街区、城市]
周边[类别]：[搜索/类别工具返回的列表，包含名称、评分、价格和距离]
行程上下文：[等时线得到的步行X分钟/驾车Y分钟]
来源：Mapbox Search、Mapbox Directions（实时数据）

示例响应：

SoMa, San Francisco, CA（实时Mapbox数据）

步行范围内的餐厅：

Bix餐厅 $$ ★8.4 — 黄金街56号（180米）

The Bird $ ★7.9 — 新蒙哥马利街115号（320米）

Oren's Hummus $$ ★8.1 — 汤森街131号（510米）

步行可达范围：5分钟、10分钟、15分钟

来源：Mapbox地理编码API、Mapbox搜索API、Mapbox地点详情API、Mapbox等时线API、Mapbox静态图像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

对于两个地点间的行程问题，使用

directions_tool

。对于可达区域问题，使用

isochrone_tool

。对于多地点间的行程时间对比，使用

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.

"从派克市场开车到国会山需要多长时间？" "从酒店到机场最快路线是什么？"

directions_tool(
  waypoints: [{longitude, latitude}, {longitude, latitude}],
  profile: "mapbox/driving-traffic"   // 实时路况；或 "mapbox/walking", "mapbox/cycling", "mapbox/driving"
)

返回：时长（含实时路况）、距离、逐向导航步骤，以及用于地图渲染的编码折线图。支持最多25个途经点的多段路线。

Area reachability ("within X minutes")

区域可达性（"X分钟内可达"）

"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

ground_location_tool

to answer "what restaurants are within a 10-minute walk?" — use the isochrone to define the boundary, then search within it.

"步行10分钟内可达的地方有什么？" "展示从这里开车15分钟内可到达的区域"

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

返回一个多边形，展示每个时间阈值内可到达的区域。结合

category_search_tool

或

ground_location_tool

回答"步行10分钟内有哪些餐厅？"——使用等时线定义边界，然后在边界内搜索。

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.

"这三个办公室中哪个离我的位置最近？" "从这个仓库到每个配送区域的行程时间是多少？" "对比到多个地点的通勤时间"

使用

matrix_tool

——请勿为每个地点对单独调用
directions_tool
。Matrix工具可在单次API调用中批量处理所有地点对。

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

返回所有起点/终点对之间的时长和距离矩阵。按时长排序结果，找到最近的地点。一次

matrix_tool

调用可替代N次单独的

directions_tool

调用。

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.

对于"在[地点]的X分钟范围内寻找[类别]"：

如有需要，对起点进行地理编码：
```
search_and_geocode_tool(address)
```

获取可达区域：

isochrone_tool(coordinates, profile, contours_minutes)

搜索POI：
```
ground_location_tool(longitude, latitude, query: "category")
```
——等时线轮廓会告知用户每个时间范围内的可达地点

或者更直接的方式：

ground_location_tool

可在一次调用中返回周边POI和等时线可达范围，无需额外组合即可覆盖大多数邻近+路径规划场景。

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)

派克市场 → 西雅图国会山

驾车（含实时路况）：12分钟，3.2公里，途经Pine St 步行：28分钟，2.1公里骑行：14分钟，2.3公里

来源：Mapbox路径规划API（实时路况）

What Mapbox Grounding Offers vs. Training Data

Mapbox锚定 vs 训练数据的优势

	Training Data	Mapbox Grounding
POI accuracy	Stale, hallucinated	Live, verified
Ratings/price	Often wrong	Live via Place Details
Business hours	Often wrong	Live via Place Details
Travel times	Estimated	Live traffic via Directions
Reachable area	Not available	Isochrone polygons
Multi-stop routing	Not available	Up to 25 waypoints
New places	Missing	Indexed
Map image	None	Inline static map
Citations	None	Tool + API source

	训练数据	Mapbox锚定
POI准确性	过时、易产生幻觉	实时、经过验证
评分/价格	常不准确	通过Place Details获取实时数据
营业时间	常不准确	通过Place Details获取实时数据
行程时间	估算值	通过Directions获取实时路况数据
可达区域	无此功能	等时线多边形
多段路线规划	无此功能	支持最多25个途经点
新地点	缺失	已收录
地图图像	无	内嵌静态地图
引用来源	无	工具+API来源

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.

属性过滤（适合家庭、户外座位、快速充电）不受类别搜索API支持。请使用类别术语，并借助评分/价格数据给出基于偏好的推荐。
POI覆盖范围因地区而异。如果搜索结果很少，请如实告知，不要编造内容。
邻近搜索需要坐标——如果用户提供的是地址，请先使用
```
search_and_geocode_tool
```
进行地理编码，再执行类别搜索。

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

不调用搜索工具，仅依靠训练数据回答"X附近有什么？"
不调用
```
directions_tool
```
或
```
isochrone_tool
```
就估算行程时间
编造商家名称、营业时间或评分

在

ground_location_tool

可用的情况下，单独调用

reverse_geocode_tool

category_search_tool

place_details_tool

使用"适合家庭"等属性术语作为查询参数——应使用类别替代
返回原始工具输出，不整理为易读的响应
省略引用来源——务必说明响应基于实时Mapbox数据