---
name: 高德地图 (qq9349540)
description: 当用户需要地理编码、POI搜索、路线规划（驾车/步行/骑行/公交）、坐标转换、天气预报、批量操作或数据导出时应使用此技能。支持高德地图 API 查询中国地理数据。
---

# 高德地图技能 v2.4.0 (Production Ready)

功能完整的 **Windows 版**高德地图命令行工具。经过**四轮**深度审查 + PowerShell Parser 零错误验证，已修复全部已知 Bug，达到生产可用状态。

> **双实现**：Python 3.8+ (`amap.py`) + PowerShell 5.1+/7+ (`amap.ps1`)，功能完全对齐。

---

## 📋 变更日志 (CHANGELOG)

### **v2.4.0** — 深度审查修复版 `2026-04-11`

| 类型 | 数量 | 说明 |
|------|------|------|
| 🔧 缺陷修复 | 6 | navi URL / 骑行信息 / DRY重构 / clear-cache / export补齐 / config清理 |
| 🔒 编码修复 | 1 | PowerShell UTF-8 BOM（PS5.1 中文兼容） |

#### 详细变更

- ✅ **[M-1] navi 导航链接统一**：PowerShell 移除多余 `from` 参数 → 与 Python 一致（`?to=坐标,名称&mode=car`）
- ✅ **[M-2] 骑行路线信息增强 (v5 API)**：新增红绿灯数(`traffic_light_count`)、路线步数(`steps`)字段输出
- ✅ **[M-3] 代码 DRY 重构**：
  - Python：抽取 `_do_http_request()` 统一 HTTP 核心，`invoke_amap_request`/`invoke_amap_v5_request` 改为薄包装
  - PowerShell：抽取 `Invoke-AMapRequestCore()` 统一核心，消除 ~90 行重复代码
- ✅ **[M-4] Shell 模式 clear-cache 对齐**：PS Shell 模式现在也显示缓存条目数
- ✅ **[M-6] Python export 命令补全**：argparse + Shell 模式新增 `export` 子命令（与 PS 完全对齐）
- ✅ **[M-8] Config 双写冗余清理**：统一单 key 驼峰格式写入；新增 `_config_get()` 多 key 兼容读取辅助函数
- ✅ **[编码]** amap.ps1 添加 UTF-8 BOM 头，解决 Windows PowerShell 5.1 解析中文报错问题

---

### **v2.3.0** — API 修复版 `2026-04-11`

| 类型 | 数量 | 说明 |
|------|------|------|
| 🔧 API 修复 | 2 | 骑行改用 v5 API / 公交改用 transit/integrated 端点 |
| ✨ 架构改进 | 3 | base_url_v5 配置 / v5 请求函数 / 公交解析增强 |

#### 详细变更

- ✅ **骑行路线修复**：v3 API 不再支持骑行 → 切换至 **v5 API** (`/v5/direction/bicycling`)
- ✅ **公交路线修复**：原端点缺少 city 参数 → 使用 `/v3/direction/transit/integrated` + 自动检测城市
- ✅ 新增 `base_url_v5` 配置项，支持 v3/v5 动态切换
- ✅ 新增 `Invoke-AMapV5Request` / `invoke_amap_v5_request` 函数
- ✅ 增强公交路线解析：支持轨道交通信息

---

### **v2.2.0** — 第三轮审查补丁

| 类型 | 数量 |
|------|------|
| 🔧 Bug 修复 | 9 |
| 🛡️ 健壮性增强 | 5 |
| ✨ 新功能 | 5 |

#### 关键修复

- 所有命令无数据时返回**结构化错误 JSON**（不再静默失败）
- `distance` 字段 null 安全处理
- 缓存 key 排序一致化（避免 hashtable 键序差异导致未命中）
- API Key 短长度保护（短 key 不再崩溃）
- `Format-Output` 中英文键名兼容（`名称` vs `Name`）
- 分页循环变量防未初始化（`$result = $null`）
- buslines 空数组越界保护（`.Count -gt 0` 校验）

#### 关键新功能

- POI **分页翻页**：`-AllPages` 自动获取全量结果
- 结果 **直接导出**：`-OutputFile <path>` 保存 JSON 文件
- **公交路线**：transit 方式完整解析（换乘/费用/上下车站/轨道交通）
- **缓存控制**：`clear-cache` 命令
- **Shell 补全**：交互模式支持全部 17 个命令

---

### **v2.1.0** — 第二轮审查增强

健壮性全面增强、Export-Data 重构、坐标格式校验等。

### **v2.0.0** — 初始发布

全功能 CLI 工具：地理编码/逆编码/天气/IP定位/POI搜索/周边搜索/POI详情/路线规划(驾车+步行)/距离测量/导航链接/打车链接/批量地理编码/批量周边搜索/交互式Shell。

---

## 快速开始

### 1. 设置 API Key

```powershell
# 方式1: 命令行设置（推荐，同时写入环境变量和配置文件）
amap set-amapkey "your-api-key"

# 方式2: 系统环境变量（Machine 级别，永久有效）
# [系统属性] → [环境变量] → [新建] → AMAP_API_KEY = your-key

# 方式3: 当前会话
$env:AMAP_API_KEY = "your-api-key"
```

### 2. 基本使用

```powershell
# 地址转坐标
amap g "蚌埠市梅桥街道"

# 周边搜索 + 分页获取全部 + 保存到文件
amap a "超市" "117.3,33.0" 2000 -AllPages -OutputFile pois.json

# 公交路线规划
amap r "117.36,32.95" "117.38,32.94" transit -Simple

# 批量地理编码
amap bg "梅桥,联盟家博城,温莎" -Simple
```

## 命令列表

### 配置命令

| 命令                       | 说明                                     | 示例                                 |
| -------------------------- | ---------------------------------------- | ------------------------------------ |
| `set-amapkey <key>`        | 设置API密钥（自动写入环境变量+配置文件） | `amap set-amapkey "xxx"`             |
| `get-amapkey`              | 查看当前密钥（脱敏显示）                 | `amap get-amapkey`                   |
| `config`                   | 查看当前配置                             | `amap config`                        |
| `config set <key> <value>` | 修改配置项                               | `amap config set defaultCity 合肥市` |
| `clear-cache`              | 清除请求缓存                             | `amap clear-cache`                   |
| `status`                   | 运行状态（版本/请求数/缓存/API Key）     | `amap status`                        |

**可配置参数：**

| 参数            | 默认值 | 说明             |
| --------------- | ------ | ---------------- |
| `defaultCity`   | 蚌埠市 | 默认搜索城市     |
| `defaultRadius` | 1500   | 默认搜索半径(米) |
| `outputFormat`  | json   | 默认输出格式     |

### 位置服务

| 命令                | 别名 | 参数                   | 说明      | 示例                   |
| ------------------- | ---- | ---------------------- | --------- | ---------------------- |
| `geo <地址> [城市]` | `g`  | `-Simple`              | 地址→坐标 | `amap g "蚌埠站"`      |
| `regeo <坐标>`      | `rg` | `-Simple`              | 坐标→地址 | `amap rg "117.3,33.0"` |
| `weather [城市]`    | `w`  | `-Format json\|simple` | 天气预报  | `amap w "蚌埠市"`      |
| `ip [IP]`           | -    | `-Simple`              | IP定位    | `amap ip`              |

### 搜索服务

| 命令                            | 别名 | 参数                            | 说明          | 示例                              |
| ------------------------------- | ---- | ------------------------------- | ------------- | --------------------------------- |
| `search <关键词> [城市]`        | `s`  | `-AllPages -OutputFile -Format` | POI关键字搜索 | `amap s "餐厅" "蚌埠" -AllPages`  |
| `around <关键词> <坐标> [半径]` | `a`  | `-AllPages -OutputFile -Format` | 周边POI搜索   | `amap a "超市" "117.3,33.0" 1500` |
| `detail <ID>`                   | `d`  | -                               | POI详情       | `amap d "B001B0I4K0"`             |

**参数说明：**

- `-AllPages`: 自动分页获取全部结果（默认只返回第一页）
- `-OutputFile <path>`: 将结果保存为 JSON 文件
- `-Format`: `json`(默认) / `table` / `simple` / `detail`

### 路线规划

| 命令                         | 别名   | 方式                                        | 说明         | 示例                                       |
| ---------------------------- | ------ | ------------------------------------------- | ------------ | ------------------------------------------ |
| `route <起点> <终点> [方式]` | `r`    | driving / walking / bicycling / **transit** | 路线规划     | `amap r "117.3,33.0" "117.4,33.1" transit` |
| `distance <起点> <终点>`     | `dist` | `-Simple`                                   | 直线距离测量 | `amap dist "117.3,33.0" "117.4,33.1"`      |

> 支持 **4 种出行方式**：驾车(driving) / 步行(walking) / 骑行(bicycling, v5 API) / 公交(transit)

### 链接生成

| 命令                               | 别名 | 说明             | 示例                                           |
| ---------------------------------- | ---- | ---------------- | ---------------------------------------------- |
| `navi <坐标> <名称>`               | `n`  | 生成高德导航链接 | `amap n "117.3,33.0" "目的地"`                 |
| `taxi <起点> <起名> <终点> <终名>` | `t`  | 生成高德打车链接 | `amap t "117.3,33.0" "家" "117.4,33.1" "公司"` |

> 坐标格式校验：无效坐标会报错提示而非生成无效链接

### 批量操作

| 命令                                      | 别名 | 说明                     | 示例                                    |
| ----------------------------------------- | ---- | ------------------------ | --------------------------------------- |
| `batch-geo <地址1,地址2,...>`             | `bg` | 批量地理编码（逗号分隔） | `amap bg "梅桥,联盟,温莎"`              |
| `batch-around <关键词,...> <坐标> [半径]` | `ba` | 批量周边搜索（多类别）   | `amap ba "餐饮,购物,银行" "117.3,33.0"` |

### 实用功能

| 命令                          | 说明                                   |
| ----------------------------- | -------------------------------------- |
| `export <type> <file> [data]` | 导出数据到 `.json` 或 `.csv` 文件      |
| `shell`                       | 进入交互式 Shell（支持所有命令）       |

## 详细使用示例

### 场景1：光纤盒覆盖区域分析

```powershell
# 1. 获取地址坐标
amap g "蚌埠市禹会区兰凤家园"

# 2. 分页获取周边全部 POI（超过25条时自动翻页）
amap a "超市" "117.389799,32.928052" 1500 -AllPages -OutputFile lanfeng_supermarket.json

# 3. 多类别批量分析
amap ba "餐饮,购物,银行,医院,学校,酒店" "117.389799,32.928052" 2000
```

### 场景2：路线与导航

```powershell
# 驾车路线
amap r "117.36,32.95" "117.38,32.94" driving -Simple
# → 距离: 2.8公里 | 时长: 8分钟

# 骑行路线 (v5 API)
amap r "117.36,32.94" "117.40,32.92" bicycling
# → 距离/时长/红绿灯数/路线步数

# 公交路线
amap r "117.36,32.95" "117.38,32.94" transit
# → 总时长、总费用、换乘次数、每段公交详情

# 生成导航链接
amap n "117.389799,32.928052" "兰凤家园"

# 步行路线
amap r "117.36,32.95" "117.38,32.94" walking -Simple
```

### 场景3：交互式使用

```powershell
amap shell
# amap> geo "蚌埠南站"
# amap> rg "117.35,32.92"
# amap> w
# amap> clear-cache
# amap> exit
```

## 输出格式

```powershell
# JSON（默认，完整结构化数据）
amap s "餐厅" "蚌埠"

# 表格（简洁表格视图）
amap a "超市" "117.3,33.0" 1000 -Format table

# 简洁（仅名称列表）
amap s "酒店" -Format simple

# 详情（逐条展示所有字段）
amap d "B001B0I4K0" -Format detail
```

## 参数规范

| 参数       | 格式说明                                        | 示例                   |
| ---------- | ----------------------------------------------- | ---------------------- |
| 坐标       | `经度,纬度`（经度在前，小数精度≥2位）           | `117.362,32.948`       |
| 半径       | 米（正整数）                                    | `1000`, `1500`, `2000` |
| 路线方式   | `driving` / `walking` / `bicycling` / `transit` | -                      |
| 地址分隔符 | 逗号或中文逗号或分号                            | `"A,B,C"` 或 `"A,B,C"` |

## 故障排查

### 问题1：API Key 无法读取

```
AMAP_API_KEY 未设置。请运行: amap set-amapkey <your-key>
```

**解决**：

- 确认已在系统环境变量中设置了 `AMAP_API_KEY`（注意是 Machine 级别）
- 设置后需要**重新打开终端窗口**才能生效
- 或直接运行 `amap set-amapkey "你的key"`

### 问题2：10003 访问超频

**原因**：高德 API 有并发/配额限制
**解决**：

- 批量操作已内置 100ms 延迟，避免超频
- 如仍超频，可增大延迟或降低并发
- 检查高德控制台的配额用量

### 问题3：坐标格式报错

```
坐标格式无效，应为: 经度,纬度 (如: 117.3,33.0)
```

**解决**：确保使用 `经度,纬度` 格式，用英文逗号分隔，且包含小数点

### 问题4：天气/POI 查询返回空

- 确认城市名称正确（建议带省市前缀如"安徽省蚌埠市"）
- 使用 `amap config set defaultCity 蚌埠市` 设置默认城市

## 获取 API Key

👉 https://console.amap.com/dev/key/app

> 选择 **「Web服务」** 类型（不是 Web端/Android/iOS）

## 注意事项

1. API Key 需要 **Web服务** 权限
2. 高德免费额度：30万次/日（基础）；超频返回 10003 错误
3. 仅支持中国境内地理数据
4. POI 单页最多 25 条，使用 `-AllPages` 可自动翻页
5. 坐标系：GCJ02（火星坐标系），与 GPS/WGS84 有偏移
6. 双实现 (Python + PowerShell) 功能完全对齐，可按需选择使用