用途:指导 AI 助手在 Mapbox 搜索中正确选用工具与参数,完成地理编码、POI 搜索和位置发现。三种工具:search_and_geocode_tool 适合具体地点、地址、品牌与命名位置(如 Starbucks、Empire State Building、123 Main Street),不要用于泛指类别;category_search_tool 适合泛指类别与复数查询(coffee shops、museums、nearby pharmacies),不要用于品牌名;reverse_geocode_tool 用于把坐标转为地址、城市、邮编。
空间约束三选:proximity 强烈推荐,用于偏置就近结果但不排除远处匹配,本地搜索务必设置,否则结果基于 IP 或全局;bbox 为硬边界,仅返回框内结果,过小会无结果;country 按 ISO 3166 alpha-2 限制国家,三者可组合。
参数要点:category_search_tool 的 limit 仅其可用,范围 1-25,默认 10,需匹配界面需求;search_and_geocode_tool 的 types 可按 poi、address、place、street、postcode、district、locality、country 过滤;auto_complete 为 true 时支持部分与模糊匹配,适合实时输入,最终查询应关闭。
反模式:品牌名用 category_search 会报错;泛指类别用 search_and_geocode 精度较低;本地搜索漏设 proximity;用 bbox 代替 proximity;无必要请求 ETA 会消耗配额;界面下拉 limit 过高;类型未过滤会返回城市而非 POI;浏览器端 Geocoding API v5 中 limit=1 而无 proximity 可能把 Lincoln Memorial 解析到伊利诺伊州,应对输入做防抖(clearTimeout + setTimeout)。