market/skills/baidu-poi-search/SKILL.zh-CN.md

百度地图 POI 搜索

L0

输入企业名称，调用百度地图地点检索 API，返回标准化 POI 数据（名称/地址/经纬度/省市）。

L1 概述

• 数据源：百度地图开放平台地点检索 API v2
• 认证：AK（个人开发者免费配额）
• 调用方式：HTTP GET（curl / HttpRequest 工具）
• 前置条件：无浏览器依赖、无额外依赖——纯 REST API

凭证获取

本技能需要百度地图 AK（访问令牌）：

1. 访问 百度地图开放平台 注册开发者账号
2. 控制台 → 应用管理 → 创建应用（启用"地点检索"服务，AK 类型选"浏览器白名单"并将白名单留空 0.0.0.0/0）
3. 将 AK 配置为环境变量 BAIDU_MAP_AK，或替换下文命令中的 {BAIDU_MAP_AK} 占位符

若本机 DesireCore 服务目录已注册百度地图服务（端点 https://api.map.baidu.com），优先通过服务目录调用，凭证由服务配置统一管理。

L2 操作步骤

1. 构造请求

curl -s --max-time 15 --ssl-no-revoke \
  "https://api.map.baidu.com/place/v2/search?query={企业名称URL编码}&region={城市或全国}&output=json&page_size=20&ak=${BAIDU_MAP_AK}"

参数说明：

参数	值	说明
query	企业名称（URL 编码）	如"华为技术有限公司"→ %E5%8D%8E%E4%B8%BA%E6%8A%80%E6%9C%AF%E6%9C%89%E9%99%90%E5%85%AC%E5%8F%B8
region	城市名或"全国"	限定检索范围；不确定时用"全国"
output	json	固定
page_size	20	每页条数（最大 20）
ak	{BAIDU_MAP_AK}	百度地图 AK（个人开发者免费申请）

2. 判断响应

• status == 0：成功，提取 results[]
• status != 0：失败，查看 message（如 101=AK参数不存在，200=AK被禁用，302=配额超限）

3. 标准化映射

对 results[] 中每条记录映射为：

{
  "source": "baidu-poi",
  "company_name": "{用户输入的企业名称}",
  "poi_name": "{result.name}",
  "address": "{result.address}",
  "latitude": "{result.location.lat}",
  "longitude": "{result.location.lng}",
  "province": "{result.province}",
  "city": "{result.city}"
}

4. 同名词过滤（尽调场景）

POI 结果可能包含同名词干扰（如"南岗华为公司"不是"华为技术有限公司"）。过滤建议：

• 精确匹配：result.name 与企业全名一致 → 标记 match=exact
• 包含匹配：result.name 包含企业全名或其简称 → 标记 match=partial
• 其他 → 标记 match=related，尽调报告单独归类

5. 输出格式

{
  "query_status": "success",
  "source": "baidu-poi",
  "total": 5,
  "results": [
    { "poi_name": "华为技术有限公司", "address": "广东省深圳市龙岗区...", "latitude": "22.656137", "longitude": "114.066131", "match": "exact" }
  ],
  "timestamp": "2026-08-31T21:00:00+08:00"
}

已知限制

• 免费配额：个人开发者有 QPS（约 3 次/秒）与日量上限（地点检索约 100 次/日，以控制台额度管理为准）
• POI ≠ 工商注册地址：返回的是地图标注地址，可能与工商注册地址不同（尽调时注意区分）
• 同名词：知名企业简称（如"华为"）会命中大量非目标 POI，建议输入企业全名

故障排查

错误码	含义	处理
0	成功	—
101	AK 参数不存在	检查 ak 参数是否正确传递
200	AK 被禁用	到百度地图开放平台控制台检查应用状态
201	AK 校验失败 / SN 校验失败	本方案使用白名单 0.0.0.0/0 类型 AK，无需 SN
302	配额超限	查看控制台额度管理，等待次日或升级配额
240	API 服务无效	AK 未勾选"地点检索"服务——到控制台修改应用勾选