Skip to main content

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 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 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-cli skill 安装到目标目录下的 amap-cli/ 子目录
  • 当目标目录不存在时会自动创建
  • 当目标目录中已存在同名 skill 时,默认报错;追加 --force 后会覆盖

路径规划

基础格式:

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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amap-cli 0.1.2
File Size Uploaded Provenance Actions
amap_cli-0.1.2.tar.gz 26.6 kB Without provenance Details for amap_cli-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amap-cli 0.1.2
File Interpreter ABI Platform Actions
amap_cli-0.1.2-py3-none-any.whl Python 3 none any Details for amap_cli-0.1.2-py3-none-any.whl

Total release size: 53.1 kB

Release files / amap_cli-0.1.2.tar.gz

Download URL amap_cli-0.1.2.tar.gz
Size 26.6 kB
Tags Source
SHA-256 checksum
How to use checksums
2068f92bc06b27f6e187e621a9e9204337c0b83ed3a192972074ff5f9297598d
BLAKE2b-256 checksum
How to use checksums
62b156d5191724b43fd115c6319f62ea2bd2bc13380e8a819e5ba6804087d210
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.21

Release files / amap_cli-0.1.2-py3-none-any.whl

Download URL amap_cli-0.1.2-py3-none-any.whl
Size 26.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f62ddcce64effa8e94ae18538c080f54d06674b05f8aefb46dd5d1a4c60e7f8
BLAKE2b-256 checksum
How to use checksums
85c6e7592cafadfcd2beb53f3120fde8b6ec3a68576d2125c30babf085c3cafe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.21

Security for amap-cli 0.1.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page