amap-cli
amap-cli 是一个基于高德开放平台 Web API 的纯命令行工具,面向终端环境和 AI Agent 使用。
功能特性
- 纯命令行调用高德地图 API
- 支持命令行写入和读取高德 API Key
- 支持地理编码
- 支持两点直线距离计算
- 支持路径规划
- 支持 POI 搜索
- 所有命令统一返回机器可读 JSON
- 提供配套的 Agent skill,便于在智能体环境中直接调用
安装与使用
方式一:直接使用 uvx 运行
项目发布到 PyPI 后,可以直接执行:
uvx amap-cli --help
配置高德 API Key:
uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
地理编码示例:
uvx amap-cli geocode --address 北京南站
路径规划示例:
uvx amap-cli route \
--from 北京南站 \
--to 天安门 \
--type driving
直线距离示例:
uvx amap-cli distance \
--from 116.397,39.909 \
--to 116.407,39.904
POI 搜索示例:
uvx amap-cli search-poi \
--keyword 星巴克 \
--city 北京 \
--pageSize 5
方式二:安装后使用
如果希望安装到本机工具目录,执行:
uv tool install amap-cli
安装完成后可直接调用:
amap-cli --help
配置和业务命令示例:
amap-cli config set --api-key <YOUR_AMAP_KEY>
amap-cli geocode --address 北京南站
amap-cli distance --from 116.397,39.909 --to 116.407,39.904
amap-cli route --from 北京南站 --to 天安门 --type driving
amap-cli search-poi --keyword 星巴克 --city 北京
Skill 使用说明
本项目提供了配套的 amap-cli skill,适合在支持 skill 的 Agent 环境中使用。
- skill 的目标是让 Agent 直接通过
uvx amap-cli调用本工具 - 使用方式与上面的“直接使用
uvx运行”一致 - 使用前先配置高德 API Key,之后即可发起地理编码、路径规划和 POI 搜索
distance命令在起终点都为坐标时可直接本地计算,不依赖 API Key- 建议 Agent 直接解析命令返回的 JSON 结果
如果需要将内置 skill 安装到指定目录,例如 Agent 的 skills 根目录,可以执行:
amap-cli install-skill --dir ~/.agents/skills
执行后会在目标目录下生成:
~/.agents/skills/amap-cli/SKILL.md
如果目标目录中已存在同名 skill,可追加 --force 覆盖:
amap-cli install-skill --dir ~/.agents/skills --force
命令说明
配置
写入 API Key:
amap-cli config set --api-key <YOUR_AMAP_KEY>
查看当前配置:
amap-cli config show
配置会按照当前操作系统规范保存在用户配置目录中。macOS 下默认路径为:
~/Library/Application Support/amap-cli/config.json
安装 Skill
基础格式:
amap-cli install-skill --dir <skills目录>
可选参数:
--force
说明:
- 会将内置的
amap-cliskill 安装到目标目录下的amap-cli/子目录 - 当目标目录不存在时会自动创建
- 当目标目录中已存在同名 skill 时,默认报错;追加
--force后会覆盖
地理编码
基础格式:
amap-cli geocode --address <结构化地址|地标名称>
可选参数:
--city
说明:
- 调用高德地理编码接口,将结构化地址或地标性名胜景区、建筑物名称解析为坐标
- 传入
--city时,会优先在对应城市范围内解析 - 返回结果中的
geocode.location为[经度, 纬度] - 返回结果中的
geocode.formattedAddress为高德返回的标准化地址 - 对于较模糊的名称,建议补充更完整地址或增加
--city
路径规划
基础格式:
amap-cli route \
--from <结构化地址|地标名称|经度,纬度> \
--to <结构化地址|地标名称|经度,纬度> \
--type <driving|walking|riding|transit>
可选参数:
--from-name--to-name--waypoints--policy--strategy--city
说明:
--waypoints和--policy仅driving支持--strategy和--city仅transit支持- 地理编码仅支持详细的结构化地址,以及地标性名胜景区、建筑物名称
- 当起点、终点或途经点使用上述名称并解析成功时,返回结果中的对应节点会附带
formattedAddress - 对于其他较模糊的名称,建议先通过
search-poi获取目标地点坐标,再调用route - 不支持
--json输入
直线距离
基础格式:
amap-cli distance \
--from <结构化地址|地标名称|经度,纬度> \
--to <结构化地址|地标名称|经度,纬度>
可选参数:
--from-name--to-name
说明:
- 当
--from和--to都是坐标时,直接在本地计算直线距离 - 当任一输入为结构化地址或地标性名胜景区、建筑物名称时,会先调用高德地理编码接口解析坐标,再做本地计算
- 当输入为上述名称时,返回结果中的
state.from.formattedAddress/state.to.formattedAddress会带上高德解析出的完整地址 - 对于其他较模糊的名称,建议先通过
search-poi获取目标地点坐标,再调用distance - 结果中的
summary.distance单位为米 - 不支持
--json输入
POI 搜索
基础格式:
amap-cli search-poi --keyword <关键词>
可选参数:
--city--center--radius--pageSize--pageIndex
说明:
- 传入
--center时执行周边搜索 - 未传入
--center时执行关键词搜索 - 不支持
--json输入
输出格式
成功时:
{
"success": true,
"data": {},
"error": null
}
失败时:
{
"success": false,
"data": null,
"error": {
"code": "INVALID_ARGUMENT",
"message": "错误说明",
"details": {}
}
}
本地开发
安装项目依赖:
uv sync
本地运行:
uv run amap-cli --help
PyPI 发布
1. 确认版本号
每次发布前,先更新 pyproject.toml 中的 version。
PyPI 不允许重复上传同一个版本号的分发包。
2. 构建分发包
uv build
构建成功后会在 dist/ 目录下生成:
*.tar.gz*.whl
3. 准备 PyPI Token
登录 PyPI 后创建 API Token,推荐通过环境变量传入:
export UV_PUBLISH_TOKEN="pypi-你的token"
4. 先发布到 TestPyPI 验证(推荐)
uv publish \
--publish-url https://test.pypi.org/legacy/ \
--check-url https://test.pypi.org/simple/
如果只是验证包能否被安装,可以执行:
uvx --index https://test.pypi.org/simple/ amap-cli --help
5. 发布到正式 PyPI
确认 TestPyPI 验证通过后,执行:
uv publish
6. 发布后验证
发布完成后,推荐优先使用 uvx 做一次快速验证:
uvx amap-cli --help
发布后,推荐优先使用 uvx amap-cli 进行一次性调用,或使用 uv tool install amap-cli 安装到本地。
Metadata
Release files for amap-cli 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amap_cli-0.1.3.tar.gz | 27.9 kB | Without provenance | Details for amap_cli-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amap_cli-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for amap_cli-0.1.3-py3-none-any.whl |
Total release size: 56.3 kB
Release files / amap_cli-0.1.3.tar.gz
| Download URL | amap_cli-0.1.3.tar.gz |
|---|---|
| Size | 27.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36cca42614b7ca09297f25119486da2f0b8009e44c8c9379bed667d90056a542
|
|
BLAKE2b-256 checksum How to use checksums |
d7821bb57bdba9e5289427c4d42219ba460af5bdc6990344d2d1feebeb670a21
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.21
|
Release files / amap_cli-0.1.3-py3-none-any.whl
| Download URL | amap_cli-0.1.3-py3-none-any.whl |
|---|---|
| Size | 28.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e770c704c159254b02d40a685d6d91df693a0584e10441dd9df4e764a181aec
|
|
BLAKE2b-256 checksum How to use checksums |
56a2bbf2be4f03dc319c099d36ad58d802401e13d97a59c24d0e5e12bf6cdaf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.21
|
Security for amap-cli 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.