mapbox-search-patterns

Mapbox 搜索模式技能

为 AI 助手提供使用 Mapbox 搜索工具的专业指导。涵盖工具选择、参数优化，以及地理编码、POI 搜索和位置发现的最佳实践。

可用搜索工具

1. search_and_geocode_tool

最适合： 特定地点、地址、品牌、命名地点

在查询包含以下内容时使用：

• 特定名称：“Starbucks on 5th Avenue”“Empire State Building”
• 品牌名称：“McDonald's”“Whole Foods”
• 地址：“123 Main Street, Seattle”“1 Times Square”
• 连锁店：“Target”
• 城市／地点：“San Francisco”“Portland”

不要用于： 通用类别（“coffee shops”“museums”）

2. category_search_tool

最适合： 通用地点类型、类别、复数查询

在查询包含以下内容时使用：

• 通用类型：“coffee shops”“restaurants”“gas stations”
• 复数形式：“museums”“hotels”“parks”
• 表达类型的短语：“any coffee shop”“all restaurants”“nearby pharmacies”
• 行业术语：“electric vehicle chargers”“ATMs”

不要用于： 特定名称或品牌

3. reverse_geocode_tool

最适合： 将坐标转换为地址、城市、城镇、邮政编码

在以下情况下使用：

• 已有 GPS 坐标，需要转换为易读地址
• 需要识别特定位置所在的地点
• 将用户位置转换为地址

工具选择决策矩阵

用户查询	工具	原因
“Find Starbucks on Main Street”	search_and_geocode_tool	特定品牌名称
“Find coffee shops nearby”	category_search_tool	通用类别，复数
“What's at 37.7749, -122.4194?”	reverse_geocode_tool	将坐标转换为地址
“Empire State Building”	search_and_geocode_tool	特定命名的 POI
“hotels in downtown Seattle”	category_search_tool	通用类型 + 位置
“Target store locations”	search_and_geocode_tool	品牌名称（即使是复数）
“any restaurant near me”	category_search_tool	通用类别 + “any” 短语
“123 Main St, Boston, MA”	search_and_geocode_tool	特定地址
“electric vehicle chargers”	category_search_tool	行业类别
“McDonald's”	search_and_geocode_tool	品牌名称

参数指南

proximity、bbox 与 country

三种限制搜索结果地理范围的方式：

1. proximity（强烈推荐）

作用： 提高靠近某个位置的结果的排序，但不会排除较远的匹配项

适用于：

• 用户说“near me”“nearby”“close to”
• 有参考点，但希望保留一定灵活性
• 希望按照与某个点的相关性对结果排序

示例：

{
  "q": "pizza",
  "proximity": {
    "longitude": -122.4194,
    "latitude": 37.7749
  }
}

为什么有效： API 会优先返回旧金山的披萨店，但如果纽约的著名披萨店相关性很高，也可能包含在结果中

重要： 有参考位置时，务必设置 proximity！如果不设置，结果将基于 IP 地址或全球范围。

2. bbox（边界框）

作用： 硬性限制——只返回边界框内的结果

适用于：

• 用户指定某个区域：“in downtown”“within this neighborhood”
• 有明确的服务区域
• 需要确保结果位于边界范围内

示例：

{
  "q": "hotel",
  "bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}

为什么有效： 可确保所有酒店都位于旧金山市中心区域内

注意： 范围太小 = 没有结果；范围太大 = 结果不相关

3. country

作用： 将结果限制在特定国家

适用于：

• 用户指定国家：“restaurants in France”
• 构建针对特定国家的功能
• 需要遵循区域边界
• 或者其他情况下也能明确看出用户需要特定国家内的结果

示例：

{
  "q": "Paris",
  "country": ["FR"] // ISO 3166 alpha-2 codes
}

为什么有效： 查找的是法国巴黎（而不是德克萨斯州的巴黎）

可以组合： proximity + country + bbox，或这三者的任意组合

决策矩阵：空间筛选器

场景	使用	原因
“查找我附近的咖啡店”	proximity	优先考虑用户位置
“西雅图市中心的咖啡店”	proximity + bbox	以市中心为中心，并限制搜索区域
“法国的酒店”	country	严格限制在国家边界内
“旧金山最好的披萨”	proximity + country ["US"]	优先考虑旧金山，并限制在美国范围内
“沿这条路线的加油站”	bbox around route	严格限制在路线走廊内
“5 英里范围内的餐厅”	proximity (then filter by distance)	优先考虑附近地点，再按距离筛选结果

设置 limit 参数

仅适用于 category_search_tool（1-25，默认值为 10）

使用场景	Limit	原因
快速建议	5	结果快速且精简
标准列表	10	默认值，平衡性良好
全面搜索	25	允许的最大值
地图可视化	25	显示所有附近选项
下拉菜单/自动补全	5	避免让 UI 信息过载

性能提示： limit 越低，响应越快

types 参数（search_and_geocode_tool）

按要素类型筛选：

类型	包含内容	适用场景
poi	兴趣点（商家、地标）	查找 POI，而非地址
address	街道地址	需要具体地址
place	城市、街区、区域	查找地区/区域
street	不带门牌号的街道名称	需要街道，而非具体地址
postcode	邮政编码	按 ZIP/邮政编码搜索
district	行政区、街区	按区域搜索
locality	城镇、村庄	搜索市镇
country	国家名称	搜索国家级地点

示例组合：

// Only POIs and addresses, no cities
{"q": "Paris", "types": ["poi", "address"]}
// Returns Paris Hotel, Paris Street, not Paris, France

// Only places (cities)
{"q": "Paris", "types": ["place"]}
// Returns Paris, France; Paris, Texas; etc.

**默认行为：**包含所有类型（通常正合所需）

auto_complete 参数（search_and_geocode_tool）

**作用：**启用部分匹配/模糊匹配

设置	行为	适用场景
true	匹配部分单词和拼写错误	用户实时输入时
false (默认值)	精确匹配	最终查询，而非自动补全

示例：

// User types "starb"
{ "q": "starb", "auto_complete": true }
// Returns: Starbucks, Starboard Tavern, etc.

适用于：

• 边输入边搜索的界面

• 处理拼写错误（“mcdonalds” -> McDonald's）

• 不完整的查询

不适用于：

• 最终/已提交的查询（精确度较低）
• 需要精确匹配时

应避免的反模式

不要：用 category_search 搜索品牌

// BAD
category_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error

// GOOD
search_and_geocode_tool({ q: 'Starbucks' });

不要：用 search_and_geocode 搜索通用类别

// BAD
search_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results

// GOOD
category_search_tool({ category: 'coffee_shop' });

不要：在本地搜索时忘记设置 proximity

// BAD - Results may be anywhere globally
category_search_tool({ category: 'restaurant' });

// GOOD - Biased to user location
category_search_tool({
  category: 'restaurant',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

不要：在未设置 proximity 时对有歧义的地名进行地理编码（REST 也适用）

这适用于浏览器应用中的 Mapbox Geocoding API v5 / Search Box，不仅适用于 MCP 工具。

// BAD — limit=1 without proximity can resolve "Lincoln Memorial" to Illinois
fetch(`https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json?access_token=${token}&limit=1`);

// GOOD — bias to map center (and optional bbox)
fetch(
  `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json` +
    `?access_token=${token}&proximity=-77.0369,38.9072&bbox=-77.15,38.79,-76.90,38.99&limit=1`
);

同时应对搜索输入进行防抖处理（clearTimeout + setTimeout），避免每次按键都触发地理编码。

不要：需要 proximity 时却使用 bbox

// BAD - Hard boundary may exclude good nearby results
search_and_geocode_tool({
  q: 'pizza',
  bbox: [-122.42, 37.77, -122.41, 37.78] // Tiny box
});

// GOOD - Bias toward point, but flexible
search_and_geocode_tool({
  q: 'pizza',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

不要：不必要地请求 ETA

// BAD - Costs API quota for routing calculations
search_and_geocode_tool({
  q: 'museums',
  eta_type: 'navigation',
  navigation_profile: 'driving'
});
// User didn't ask for travel time!

// GOOD - Only add ETA when needed
search_and_geocode_tool({ q: 'museums' });
// If user asks "how long to get there?", then add ETA

不要：为 UI 展示设置过高的 limit

// BAD - Overwhelming for simple dropdown
category_search_tool({
  category: 'restaurant',
  limit: 25
});
// Returns 25 restaurants for a 5-item dropdown

// GOOD - Match UI needs
category_search_tool({
  category: 'restaurant',
  limit: 5
});

快速参考

工具选择流程图

User query contains...

-> Specific name/brand (Starbucks, Empire State Building)
  -> search_and_geocode_tool

-> Generic category/plural (coffee shops, museums, any restaurant)
  -> category_search_tool

-> Coordinates -> Address
  -> reverse_geocode_tool

-> Address -> Coordinates
  -> search_and_geocode_tool with types: ["address"]

必要参数清单

进行本地搜索时，始终设置：

• proximity（如果需要严格限定边界，则使用 bbox）

进行类别搜索时，请考虑：

• limit（匹配 UI 需求）
• format（如果要在地图上绘图，则使用 json_string）

消除歧义时，使用：

• country（地理位置背景很重要时）
• types（要素类型很重要时）

按出行时间排序时：

• eta_type、navigation_profile、origin（会消耗 API 配额）

常见错误

1. 忘记设置 proximity -> 结果基于全球范围/IP 定位（或对于有歧义的纪念馆/公园名称，返回错误的州）
2. 使用了错误的工具 -> 对“Starbucks”使用 category_search（应使用 search_and_geocode）
3. 类别无效 -> 首先检查 category_list
4. Bbox 过小 -> 没有结果；改用 proximity
5. 不必要地请求 ETA -> 增加 API 成本
6. UI 的 limit 过高 -> 结果多到让用户应接不暇
7. 未筛选 types -> 想要 POI 时却得到城市
8. 输入提示没有防抖 -> 消耗配额且 UI 存在竞态问题

参考文件

针对特定主题的深入指导，请加载以下文件：

• references/advanced-params.md — poi_category、ETA、format 和 language 参数
• references/workflows.md — 常见模式：附近搜索、品牌搜索、地理编码、类别+区域、反向搜索、路线搜索、多语言
• references/optimization-combining.md — 性能优化、组合工具、处理无结果的情况、类别列表资源