mapbox-search-patterns by mapbox/mapbox-agent-skills
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-search-patterns为 AI 助手提供关于有效使用 Mapbox 搜索工具的专家指导。涵盖工具选择、参数优化以及地理编码、POI 搜索和位置发现的最佳实践。
最适合: 特定地点、地址、品牌、命名位置
当查询包含以下内容时使用:
不要用于: 通用类别("coffee shops"、"museums")
最适合: 通用地点类型、类别、复数查询
当查询包含以下内容时使用:
不要用于: 特定名称或品牌
最适合: 将坐标转换为地址、城市、城镇、邮政编码
在以下情况使用:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 用户查询 | 工具 | 推理 |
|---|---|---|
| "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 | 品牌名称 |
三种空间约束搜索结果的方式:
作用: 使结果偏向某个位置,但不排除远处的匹配项
在以下情况使用:
示例:
{
"q": "pizza",
"proximity": {
"longitude": -122.4194,
"latitude": 37.7749
}
}
为何有效: API 会优先返回旧金山的披萨店,但如果相关性很高,也可能包括著名的纽约披萨店
⚠️ 关键: 当你有参考位置时,务必设置 proximity!否则,结果将基于 IP 或全球范围。
作用: 硬性约束 - 仅返回框内的结果
在以下情况使用:
示例:
{
"q": "hotel",
"bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}
为何有效: 保证所有酒店都在旧金山市中心区域内
⚠️ 注意: 太小 = 没有结果;太大 = 不相关的结果
作用: 将结果限制在特定国家
在以下情况使用:
示例:
{
"q": "Paris",
"country": ["FR"] // ISO 3166 alpha-2 代码
}
为何有效: 找到法国巴黎(而不是德克萨斯州巴黎)
可以组合使用: proximity + country + bbox 或三者的任意组合
| 场景 | 使用 | 原因 |
|---|---|---|
| "Find coffee near me" | proximity | 偏向用户位置 |
| "Coffee shops in downtown Seattle" | proximity + bbox | 以市中心为中心,限制在区域内 |
| "Hotels in France" | country | 硬性国家边界 |
| "Best pizza in San Francisco" | proximity + country ["US"] | 偏向旧金山,限制在美国 |
| "Gas stations along this route" | bbox around route | 硬性约束到路线走廊 |
| "Restaurants within 5 miles" | proximity (然后按距离过滤) | 偏向附近,过滤结果 |
仅限 category_search_tool(1-25,默认 10)
| 使用场景 | Limit | 推理 |
|---|---|---|
| 快速建议 | 5 | 快速、集中的结果 |
| 标准列表 | 10 | 默认值,良好的平衡 |
| 全面搜索 | 25 | 允许的最大值 |
| 地图可视化 | 25 | 显示所有附近选项 |
| 下拉/自动完成 | 5 | 不使 UI 过载 |
性能提示: 较低的 limit = 更快的响应
按要素类型过滤:
| 类型 | 包含内容 | 使用时机 |
|---|---|---|
poi | 兴趣点(企业、地标) | 寻找 POI,而非地址 |
address | 街道地址 | 需要具体地址 |
place | 城市、街区、区域 | 寻找区域/地区 |
street | 无门牌号的街道名称 | 需要街道,而非具体地址 |
postcode | 邮政编码 | 按 ZIP/邮政编码搜索 |
district | 区、街区 | 基于区域的搜索 |
locality | 城镇、村庄 | 市政区域搜索 |
country | 国家名称 | 国家级搜索 |
示例组合:
// 仅 POI 和地址,不包括城市
{"q": "Paris", "types": ["poi", "address"]}
// 返回巴黎酒店、巴黎街,而不是法国巴黎
// 仅地点(城市)
{"q": "Paris", "types": ["place"]}
// 返回法国巴黎;德克萨斯州巴黎;等等。
默认行为: 包含所有类型(通常是你想要的)
search_and_geocode_tool: 缩小通用搜索范围
{
"q": "lunch",
"poi_category": ["restaurant", "cafe"],
"proximity": { "longitude": -122.4194, "latitude": 37.7749 }
}
何时使用:
category_search_tool: 使用 poi_category_exclusions 代替
{
"category": "food_and_drink",
"poi_category_exclusions": ["bar", "nightclub"]
}
何时使用:
作用: 启用部分/模糊匹配
| 设置 | 行为 | 使用时机 |
|---|---|---|
true | 匹配部分单词、拼写错误 | 用户实时输入时 |
false(默认) | 精确匹配 | 最终查询,非自动完成 |
示例:
// 用户输入 "starb"
{ "q": "starb", "auto_complete": true }
// 返回:Starbucks, Starboard Tavern 等。
用于:
不要用于:
请求到结果的预计到达时间
参数:
eta_type:设置为 "navigation"navigation_profile:"driving" | "walking" | "cycling"origin:起始坐标在以下情况使用:
示例:
{
"q": "grocery stores",
"proximity": { "longitude": -122.4194, "latitude": 37.7749 },
"eta_type": "navigation",
"navigation_profile": "driving",
"origin": { "longitude": -122.4194, "latitude": 37.7749 }
}
返回: 带有 eta(旅行时间,秒)的结果
⚠️ 成本: 每个结果都需要路由计算(计入 API 配额)
何时不使用:
选择输出格式:
| 格式 | 返回内容 | 使用时机 |
|---|---|---|
formatted_text(默认) | 人类可读的文本 | 直接显示给用户 |
json_string | GeoJSON 作为 JSON 字符串 | 需要解析/处理结果 |
示例:
formatted_text:
1. Blue Bottle Coffee
地址:66 Mint St, San Francisco, CA
坐标:37.7825, -122.4052
类型:poi
json_string:
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [-122.4052, 37.7825]},
"properties": {"name": "Blue Bottle Coffee", ...}
}]
}
决策:
formatted_textjson_string(解析并使用坐标)json_stringISO 语言代码(例如,"en"、"es"、"fr"、"de"、"ja"、"zh")
在以下情况使用:
示例:
{
"q": "東京タワー",
"language": "ja"
}
// 返回日语结果
默认: 英语(如果未指定)
提示: 匹配用户的区域设置以获得最佳体验
用户: "Find coffee shops near me"
最佳方法:
1. 获取用户位置(来自应用/浏览器)
2. 使用 category_search_tool:
- category: "coffee_shop"
- proximity: 用户坐标
- limit: 10
原因: 类别工具用于通用 "coffee shops",proximity 用于 "near me"
用户: "Find all Starbucks in Seattle"
最佳方法:
1. 使用 search_and_geocode_tool:
- q: "Starbucks"
- proximity: 西雅图坐标
- country: ["US"]
2. 或者如果需要严格边界:
- bbox: 西雅图城市边界
原因: 品牌名称 = search_and_geocode_tool;proximity 偏向西雅图
用户: "What are the coordinates of 1600 Pennsylvania Ave?"
最佳方法:
使用 search_and_geocode_tool:
- q: "1600 Pennsylvania Ave, Washington DC"
- types: ["address"] // 专注于地址
- country: ["US"] // 限制在美国
原因: 带有国家上下文的特定地址以消除歧义
用户: "Show me all hotels in downtown Portland"
最佳方法:
1. 地理编码 "downtown Portland" → 获取中心点
2. 定义市中心 bbox(或使用 1-2 英里半径)
3. 使用 category_search_tool:
- category: "hotel"
- bbox: 市中心边界(或 proximity + 按距离过滤)
- limit: 25 // 获取全面列表
原因: 类别用于 "hotels",bbox 用于 "in downtown" 硬性边界
用户: "What's at these GPS coordinates?"
最佳方法:
使用 reverse_geocode_tool:
- longitude: -122.4194
- latitude: 37.7749
- types: ["address"] // 获取地址(也可以使用 place, locality, postcode 等)
原因: 坐标 → 地址正是反向地理编码的作用
用户: "Find gas stations along my route"
最佳方法:
1. 从 directions_tool 获取路线几何形状
2. 创建路线周围的 bbox(使用 bounding_box_tool)
3. 使用 category_search_tool:
- category: "gas_station"
- bbox: 路线边界框
4. 过滤结果,只保留距离路线 X 米内的结果(使用 distance_tool)
原因: Bbox 用于粗略过滤,然后距离计算用于精确度
用户: "Find ramen shops"(用户区域设置:ja)
最佳方法:
使用 category_search_tool:
- category: "ramen_restaurant"(或 "restaurant")
- language: "ja"
- proximity: 用户位置
原因: 返回日语名称/地址以获得更好的用户体验
// 错误
category_search_tool({ category: 'starbucks' });
// "starbucks" 不是类别,返回错误
// 正确
search_and_geocode_tool({ q: 'Starbucks' });
// 错误
search_and_geocode_tool({ q: 'coffee shops' });
// 精度较低,可能返回不相关的结果
// 正确
category_search_tool({ category: 'coffee_shop' });
// 错误 - 结果可能来自全球任何地方
category_search_tool({ category: 'restaurant' });
// 正确 - 偏向用户位置
category_search_tool({
category: 'restaurant',
proximity: { longitude: -122.4194, latitude: 37.7749 }
});
// 错误 - 硬性边界可能排除附近的好结果
search_and_geocode_tool({
q: 'pizza',
bbox: [-122.42, 37.77, -122.41, 37.78] // 小框
});
// 正确 - 偏向某点,但灵活
search_and_geocode_tool({
q: 'pizza',
proximity: { longitude: -122.4194, latitude: 37.7749 }
});
// 错误 - 为路由计算消耗 API 配额
search_and_geocode_tool({
q: 'museums',
eta_type: 'navigation',
navigation_profile: 'driving'
});
// 用户没有询问旅行时间!
// 正确 - 仅在需要时添加 ETA
search_and_geocode_tool({ q: 'museums' });
// 如果用户问 "how long to get there?",则添加 ETA
// 错误 - 对于简单的下拉菜单来说过于庞大
category_search_tool({
category: 'restaurant',
limit: 25
});
// 为 5 项下拉菜单返回 25 家餐厅
// 正确 - 匹配 UI 需求
category_search_tool({
category: 'restaurant',
limit: 5
});
模式:地理编码一次,重复使用坐标
// 正确
1. 用户输入 "Seattle"
2. 地理编码 "Seattle" → (lng, lat)
3. 将这些坐标用于多个类别搜索
4. 为会话缓存坐标
// 错误
1. 为咖啡搜索地理编码 "Seattle"
2. 再次为餐厅搜索地理编码 "Seattle"
3. 再次为酒店搜索地理编码 "Seattle"
| UI 上下文 | 推荐限制 |
|---|---|
| 自动完成下拉菜单 | 5 |
| 列表视图 | 10 |
| 地图视图 | 25 |
| 导出/下载 | 25(或分页) |
获取搜索结果后:
1. category_search_tool → 获取 POI
2. distance_tool(离线)→ 计算距离
3. bearing_tool(离线)→ 获取方向
原因: 搜索一次(API),然后使用离线工具进行计算(免费、快速)
1. category_search_tool({category: "hospital", proximity: user_location})
→ 返回 10 个带坐标的医院
2. distance_tool(user_location, each_hospital)
→ 离线计算精确距离
3. 按距离排序
1. search_and_geocode_tool({q: "Space Needle"})
→ 获取目的地坐标
2. directions_tool({from: user_location, to: space_needle_coords})
→ 获取逐向导航
1. search_and_geocode_tool({q: "warehouse"})
→ 获取仓库坐标
2. isochrone_tool({coordinates: warehouse, time: 30, profile: "driving"})
→ 获取 30 分钟配送区域多边形
3. point_in_polygon_tool(customer_address, delivery_zone)
→ 检查客户是否在配送区域内
1. category_search_tool({category: "restaurant", limit: 10})
→ 获取餐厅坐标
2. static_map_image_tool({
markers: restaurant_coordinates,
auto_fit: true
})
→ 创建显示所有餐厅的地图图像
可能的原因:
resource_reader_tool 和 mapbox://categories 查看有效类别示例恢复:
1. category_search_tool({category: "taco"}) → 无结果
2. 检查:"taco" 是有效类别吗?
→ 使用 category_list_tool → 看到 "mexican_restaurant" 是有效的
3. 重试:category_search_tool({category: "mexican_restaurant"}) → 成功
可能的原因:
auto_complete: true 重试获取有效类别: 使用 resource_reader_tool 或 category_list_tool
resource_reader_tool({uri: "mapbox://categories"})
返回: 所有有效的类别 ID(例如,"restaurant"、"hotel"、"gas_station")
何时使用:
示例映射:
用户查询包含...
→ 特定名称/品牌(Starbucks, Empire State Building)
→ search_and_geocode_tool
→ 通用类别/复数(coffee shops, museums, any restaurant)
→ category_search_tool
→ 坐标 → 地址
→ reverse_geocode_tool
→ 地址 → 坐标
→ search_and_geocode_tool with types: ["address"]
对于本地搜索,务必设置:
proximity(如果需要严格边界,则使用 bbox)对于类别搜索,考虑:
limit(匹配 UI 需求)format(如果在地图上绘制,则使用 json_string)对于消除歧义,使用:
country(当地理位置上下文重要时)types(当要素类型重要时)对于旅行时间排名:
eta_type, navigation_profile, origin(消耗 API 配额)可与以下技能配合使用:
每周安装次数
257
代码仓库
GitHub Stars
36
首次出现
Feb 10, 2026
安全审计
安装于
gemini-cli243
opencode243
codex241
github-copilot241
amp233
kimi-cli233
Expert guidance for AI assistants on using Mapbox search tools effectively. Covers tool selection, parameter optimization, and best practices for geocoding, POI search, and location discovery.
Best for: Specific places, addresses, brands, named locations
Use when query contains:
Don't use for: Generic categories ("coffee shops", "museums")
Best for: Generic place types, categories, plural queries
Use when query contains:
Don't use for: Specific names or brands
Best for: Converting coordinates to addresses, cities, towns, postcodes
Use when:
| User Query | Tool | Reasoning |
|---|---|---|
| "Find Starbucks on Main Street" | search_and_geocode_tool | Specific brand name |
| "Find coffee shops nearby" | category_search_tool | Generic category, plural |
| "What's at 37.7749, -122.4194?" | reverse_geocode_tool | Coordinates to address |
| "Empire State Building" | search_and_geocode_tool | Specific named POI |
| "hotels in downtown Seattle" | category_search_tool | Generic type + location |
| "Target store locations" | search_and_geocode_tool | Brand name (even plural) |
| "any restaurant near me" | category_search_tool | Generic + "any" phrase |
| "123 Main St, Boston, MA" | search_and_geocode_tool | Specific address |
| "electric vehicle chargers" | category_search_tool |
Three ways to spatially constrain search results:
What it does: Biases results toward a location, but doesn't exclude distant matches
Use when:
Example:
{
"q": "pizza",
"proximity": {
"longitude": -122.4194,
"latitude": 37.7749
}
}
Why this works: API returns SF pizza places first, but might include famous NYC pizzerias if highly relevant
⚠️ Critical: Always set proximity when you have a reference location! Without it, results are IP-based or global.
What it does: Hard constraint - ONLY returns results within the box
Use when:
Example:
{
"q": "hotel",
"bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}
Why this works: Guarantees all hotels are within SF's downtown area
⚠️ Watch out: Too small = no results; too large = irrelevant results
What it does: Limits results to specific countries
Use when:
Example:
{
"q": "Paris",
"country": ["FR"] // ISO 3166 alpha-2 codes
}
Why this works: Finds Paris, France (not Paris, Texas)
Can combine: proximity + country + bbox or any combination of the three
| Scenario | Use | Why |
|---|---|---|
| "Find coffee near me" | proximity | Bias toward user location |
| "Coffee shops in downtown Seattle" | proximity + bbox | Center on downtown, limit to area |
| "Hotels in France" | country | Hard country boundary |
| "Best pizza in San Francisco" | proximity + country ["US"] | Bias to SF, limit to US |
| "Gas stations along this route" | bbox around route | Hard constraint to route corridor |
| "Restaurants within 5 miles" | proximity (then filter by distance) | Bias nearby, filter results |
category_search_tool only (1-25, default 10)
| Use Case | Limit | Reasoning |
|---|---|---|
| Quick suggestions | 5 | Fast, focused results |
| Standard list | 10 | Default, good balance |
| Comprehensive search | 25 | Maximum allowed |
| Map visualization | 25 | Show all nearby options |
| Dropdown/autocomplete | 5 | Don't overwhelm UI |
Performance tip: Lower limits = faster responses
Filter by feature type:
| Type | What It Includes | Use When |
|---|---|---|
poi | Points of interest (businesses, landmarks) | Looking for POIs, not addresses |
address | Street addresses | Need specific address |
place | Cities, neighborhoods, regions | Looking for area/region |
street | Street names without numbers | Need street, not specific address |
postcode | Postal codes |
Example combinations:
// 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.
Default behavior: All types included (usually what you want)
search_and_geocode_tool: Narrow generic searches
{
"q": "lunch",
"poi_category": ["restaurant", "cafe"],
"proximity": { "longitude": -122.4194, "latitude": 37.7749 }
}
When to use:
category_search_tool: Use poi_category_exclusions instead
{
"category": "food_and_drink",
"poi_category_exclusions": ["bar", "nightclub"]
}
When to use:
What it does: Enables partial/fuzzy matching
| Setting | Behavior | Use When |
|---|---|---|
true | Matches partial words, typos | User typing in real-time |
false (default) | Exact matching | Final query, not autocomplete |
Example:
// User types "starb"
{ "q": "starb", "auto_complete": true }
// Returns: Starbucks, Starboard Tavern, etc.
Use for:
Search-as-you-type interfaces
Handling typos ("mcdonalds" → McDonald's)
Incomplete queries
Don't use for:
Request estimated time of arrival to results
Parameters:
eta_type: Set to "navigation"navigation_profile: "driving" | "walking" | "cycling"origin: Starting coordinatesUse when:
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)
⚠️ Cost: Requires routing calculation per result (counts toward API quota)
When NOT to use:
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:
formatted_textjson_string (parse and use coordinates)json_stringISO language codes (e.g., "en", "es", "fr", "de", "ja", "zh")
Use when:
Example:
{
"q": "東京タワー",
"language": "ja"
}
// Returns results in Japanese
Default: English (if not specified)
Tip: Match user's locale for best experience
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"
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
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
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
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
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
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
// BAD
category_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error
// GOOD
search_and_geocode_tool({ q: 'Starbucks' });
// BAD
search_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results
// GOOD
category_search_tool({ category: 'coffee_shop' });
// 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 }
});
// 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 }
});
// 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
// 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
});
Pattern: Geocode once, reuse coordinates
// GOOD
1. User enters "Seattle"
2. Geocode "Seattle" → (lng, lat)
3. Use those coordinates for multiple category searches
4. Cache coordinates for session
// BAD
1. Geocode "Seattle" for coffee search
2. Geocode "Seattle" again for restaurant search
3. Geocode "Seattle" again for hotel search
| UI Context | Recommended Limit |
|---|---|
| Autocomplete dropdown | 5 |
| List view | 10 |
| Map view | 25 |
| Export/download | 25 (or paginate) |
After getting search results:
1. category_search_tool → Get POIs
2. distance_tool (offline) → Calculate distances
3. bearing_tool (offline) → Get directions
Why: Search once (API), then use offline tools for calculations (free, fast)
1. category_search_tool({category: "hospital", proximity: user_location})
→ Returns 10 hospitals with coordinates
2. distance_tool(user_location, each_hospital)
→ Calculate exact distances offline
3. Sort by distance
1. search_and_geocode_tool({q: "Space Needle"})
→ Get destination coordinates
2. directions_tool({from: user_location, to: space_needle_coords})
→ Get turn-by-turn directions
1. search_and_geocode_tool({q: "warehouse"})
→ Get warehouse coordinates
2. isochrone_tool({coordinates: warehouse, time: 30, profile: "driving"})
→ Get 30-minute delivery zone polygon
3. point_in_polygon_tool(customer_address, delivery_zone)
→ Check if customer is in delivery zone
1. category_search_tool({category: "restaurant", limit: 10})
→ Get restaurant coordinates
2. static_map_image_tool({
markers: restaurant_coordinates,
auto_fit: true
})
→ Create map image showing all restaurants
Possible reasons:
resource_reader_tool with mapbox://categories to see valid categoriesExample recovery:
1. category_search_tool({category: "taco"}) → No results
2. Check: Is "taco" a valid category?
→ Use category_list_tool → See "mexican_restaurant" is valid
3. Retry: category_search_tool({category: "mexican_restaurant"}) → Success
Possible reasons:
auto_complete: trueGet valid categories: Use resource_reader_tool or category_list_tool
resource_reader_tool({uri: "mapbox://categories"})
Returns: All valid category IDs (e.g., "restaurant", "hotel", "gas_station")
When to use:
Example mapping:
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"]
For local searches, ALWAYS set:
proximity (or bbox if strict boundary needed)For category searches, consider:
limit (match UI needs)format (json_string if plotting on map)For disambiguation, use:
country (when geographic context matters)types (when feature type matters)For travel-time ranking:
eta_type, navigation_profile, origin (costs API quota)Works with:
Weekly Installs
257
Repository
GitHub Stars
36
First Seen
Feb 10, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli243
opencode243
codex241
github-copilot241
amp233
kimi-cli233
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
140,500 周安装
系统设计框架:大规模分布式系统设计原则、四步流程与构建模块详解
251 周安装
Gluestack UI v4 设计模式指南:React Native 组件库样式规范与最佳实践
251 周安装
Notion知识捕获插件:将对话内容自动转化为结构化文档,提升团队知识管理效率
251 周安装
Shopify开发技能 - 集成ClaudeKit的电商自动化与AI助手解决方案
251 周安装
Hono Cloudflare Workers 教程 - 构建边缘API与无服务器应用
252 周安装
阿里云OpenSearch向量检索版使用指南:Python SDK推送文档与HA/SQL搜索教程
252 周安装
| Industry category |
| "McDonald's" | search_and_geocode_tool | Brand name |
| Searching by ZIP/postal code |
district | Districts, neighborhoods | Area-based search |
locality | Towns, villages | Municipality search |
country | Country names | Country-level search |