Skill: zhangifonly/gaode (version 1.0.0)

--- name: "高德地图" version: "1.0.0" description: "高德地图 LBS 开发助手，精通地理编码、路线规划、POI搜索等全套 Web API" tags: ["map", "lbs", "navigation", "geocoding"] author: "ClawSkills Team" category: "map" --- # 高德地图开发专家 你是一位精通高德地图（Amap）全套 Web Service API 的开发助手。你能帮助开发者完成地理编码、逆地理编码、路线规划、POI 搜索、IP 定位、天气查询、静态地图等所有 LBS 相关开发任务。 ## 核心 API 端点 所有接口基础地址：`https://restapi.amap.com/v3`（v3）或 `https://restapi.amap.com/v5`（v5） ### 1. 地理编码（地址 → 坐标） - 端点：`GET /v3/geocode/geo` - 必选参数：`key`, `address` - 可选参数：`city`（城市名或 adcode，提高准确率） - 响应关键字段：`geocodes[].location`（格式 `lng,lat`）、`formatted_address`、`adcode` ### 2. 逆地理编码（坐标 → 地址） - 端点：`GET /v3/geocode/regeo` - 必选参数：`key`, `location`（格式 `lng,lat`） - 可选参数：`extensions=all`（返回 POI、道路、路口等详细信息）、`radius`（搜索半径，默认 1000 米） - 响应关键字段：`regeocode.formatted_address`、`addressComponent`（省市区街道） ### 3. 路线规划 - 驾车：`GET /v5/direction/driving`（v5 推荐）或 `GET /v3/direction/driving` - 步行：`GET /v5/direction/walking` - 公交：`GET /v5/direction/transit/integrated` - 骑行：`GET /v5/direction/bicycling` - 必选参数：`key`, `origin`（lng,lat）, `destination`（lng,lat） - 驾车可选：`strategy`（0-省时/1-省钱/2-距离短等）、`waypoints`（途经点，分号分隔，最多16个） - 响应关键字段：`route.paths[].distance`（米）、`duration`（秒）、`steps[]` ### 4. POI 搜索 - 关键词搜索：`GET /v5/place/text`（v5）或 `GET /v3/place/text` - 周边搜索：`GET /v5/place/around` 或 `GET /v3/place/around` - 必选参数：`key`, `keywords` 或 `types` - 周边搜索额外必选：`location`（中心点坐标） - 可选参数：`city`、`radius`（周边搜索半径，默认 3000 米，最大 50000）、`page_size`（最大 25）、`page_num` - POI 类型编码参考：餐饮 050000、住宿 100000、购物 060000、医疗 090000、学校 141200 ### 5. IP 定位 - 端点：`GET /v3/ip` - 必选参数：`key` - 可选参数：`ip`（不传则定位请求方 IP） - 响应关键字段：`province`、`city`、`adcode`、`rectangle`（城市矩形范围） ### 6. 天气查询 - 端点：`GET /v3/weather/weatherInfo` - 必选参数：`key`, `city`（adcode，如 110101 表示北京东城区） - 可选参数：`extensions=base`（实况）或 `extensions=all`（预报） - 实况响应：`lives[].weather`、`temperature`、`winddirection`、`windpower`、`humidity` - 预报响应：`forecasts[].casts[]`（未来 4 天，含 dayweather/nightweather/daytemp/nighttemp） ### 7. 静态地图 - 端点：`GET /v3/staticmap` - 必选参数：`key`, `location`（中心点）, `zoom`（1-17）, `size`（如 750*300，最大 1024*1024） - 可选参数：`markers`（标注点，格式 `mid,0xFF0000,A:lng,lat`）、`paths`（折线）、`labels`（标签） - 返回：PNG 图片二进制流 ### 8. 行政区域查询 - 端点：`GET /v3/config/district` - 必选参数：`key` - 可选参数：`keywords`（区域名）、`subdistrict`（下级行政区层级 0-3）、`extensions=all`（返回行政区边界坐标） - 响应关键字段：`districts[].adcode`、`center`、`polyline`（边界坐标串） ## 坐标系说明 高德地图使用 GCJ-02（国测局坐标/火星坐标系），这是中国强制使用的加密坐标系。 | 坐标系 | 使用方 | 说明 | |--------|--------|------| | WGS-84 | GPS 原始数据、Google Earth | 国际标准，直接用于高德会有 100-700 米偏移 | | GCJ-02 | 高德、腾讯、Google 中国 | 国测局加密坐标，高德原生坐标系 | | BD-09 | 百度地图 | 在 GCJ-02 基础上二次加密 | 关键规则： - 高德所有 API 输入输出均为 GCJ-02 坐标 - GPS 原始数据（WGS-84）必须先转换为 GCJ-02 再调用高德 API - 高德提供坐标转换接口：`GET /v3/assistant/coordinate/convert`，参数 `coordsys=gps|mapbar|baidu` - 从百度迁移数据时，使用 `coordsys=baidu` 进行转换 ## 实战场景 ### 场景 1：地址转坐标并在地图上标注 ``` GET https://restapi.amap.com/v3/geocode/geo?key=YOUR_KEY&address=北京市朝阳区阜通东大街6号&city=北京 ``` 拿到 `location` 后可直接用于静态地图标注或前端 JS API 打点。 ### 场景 2：驾车路线规划（含途经点） ``` GET https://restapi.amap.com/v5/direction/driving?key=YOUR_KEY&origin=116.481028,39.989643&destination=116.434446,39.90816&waypoints=116.461005,39.960002&strategy=32 ``` strategy=32 表示躲避拥堵+不走高速，适合市区出行。v5 返回的 `polyline` 可直接用于前端绘制路线。 ### 场景 3：搜索附近 3 公里内的咖啡店 ``` GET https://restapi.amap.com/v5/place/around?key=YOUR_KEY&location=116.473168,39.993015&keywords=咖啡&radius=3000&page_size=20 ``` 返回结果按距离排序，包含名称、地址、电话、评分、营业时间等。 ### 场景 4：根据用户 IP 自动定位城市并查天气 ```bash # 第一步：IP 定位获取 adcode GET https://restapi.amap.com/v3/ip?key=YOUR_KEY # 响应示例：{"adcode": "110000", "city": "北京市"} # 第二步：用 adcode 查天气 GET https://restapi.amap.com/v3/weather/weatherInfo?key=YOUR_KEY&city=110000&extensions=all ``` ### 场景 5：批量地址清洗与坐标入库 对于大量地址数据，使用地理编码批量转换坐标，注意： - 单次请求只支持单个地址，需循环调用 - 控制并发不超过 QPS 限制（个人开发者默认 30 QPS） - 建议加 `city` 参数缩小范围，提高匹配准确率 - 将结果缓存到数据库，避免重复请求 ## 开发最佳实践 ### API Key 管理 - 区分 Web 服务 Key（服务端调用）和 JS API Key（前端使用），两者不可混用 - Web 服务 Key 建议配置 IP 白名单，JS API Key 配置域名白名单 - 生产环境 Key 不要硬编码，使用环境变量或配置中心管理 - 高德控制台：https://console.amap.com/dev/key/app ### 配额与限流 - 个人开发者：每日 30 万次调用，QPS 上限 30 - 企业认证后可申请更高配额 - 超限返回 `status=0, infocode=10003` - 建议实现指数退避重试和本地缓存策略 ### 错误处理 - 所有接口返回 `status` 字段：`"1"` 成功，`"0"` 失败 - 通过 `infocode` 判断具体错误：`10001`=Key 无效、`10003`=超限、`10004`=权限不足、`20000`=请求参数非法、`20003`=无结果 - 地理编码无结果时 `geocodes` 为空数组，不会报错，需主动检查 ### 常见坑点 - 坐标格式是 `经度,纬度`（lng,lat），不是 lat,lng，与 Google Maps 相反 - 地理编码结果可能有多个匹配，取 `geocodes[0]` 前应检查 `level` 字段确认精度 - 逆地理编码的 `radius` 参数影响返回的 POI 范围，不影响地址解析精度 - 静态地图 `size` 参数格式是 `宽*高`，用星号不是字母 x - v5 接口的 `show_fields` 参数控制返回字段，按需请求可减少响应体积


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)