@maptec/cli

Maptec 地图服务命令行工具。面向开发者与 AI Agent，提供地理编码、地点检索与路线规划能力，并以结构化 JSON 输出结果。

安装

npm install -g @maptec/cli

也可通过 npx 临时运行：

npx @maptec/cli --help

要求 Node.js ≥ 18。

快速开始

maptec init
maptec config get
maptec geocode --address "Orchard Road" --region SG --format json

maptec init 将引导配置 API Key 与 Base URL，并写入 ~/.maptec/config.json。

配置

配置文件

路径：~/.maptec/config.json

| 字段 | 说明 | 默认值 | |------|------|--------| | apiKey | Maptec API Key | 必填 | | baseUrl | WebAPI 根地址 | 必填 | | defaultFormat | 输出格式：json | table | json | | timeoutMs | 请求超时（毫秒） | 30000 |

{
  "apiKey": "YOUR_API_KEY",
  "baseUrl": "https://api.maptec.com",
  "defaultFormat": "json",
  "timeoutMs": 30000
}

环境变量

| 变量 | 说明 | |------|------| | MAPTEC_API_KEY | 覆盖配置文件中的 API Key | | MAPTEC_BASE_URL | 覆盖 Base URL | | MAPTEC_API_URL | MAPTEC_BASE_URL 的兼容别名 |

Base URL 解析顺序：MAPTEC_BASE_URL → MAPTEC_API_URL → 配置文件 baseUrl。

命令行配置

maptec config get
maptec config set api-key YOUR_API_KEY
maptec config set base-url https://api.maptec.com
maptec config set default-format json
maptec config set timeout 60000

config set 支持的键：api-key、base-url、default-format、timeout（及其驼峰别名）。

全局选项

| 选项 | 说明 | 默认值 | |------|------|--------| | --format <json\|table> | 输出格式 | json | | --out <file> | 将结果写入文件 | — | | --quiet | 减少 stderr 提示信息 | false | | --timeout <ms> | 覆盖请求超时 | 配置文件值 | | --fields <list> | 裁剪输出字段（逗号分隔） | — | | -V, --version | 显示版本号 | — |

成功输出

{
  "ok": true,
  "command": "geocode",
  "data": {}
}

退出码

| 码 | 含义 | |----|------| | 0 | 成功 | | 1 | 参数错误 | | 2 | 未配置 apiKey 或 baseUrl | | 3 | API 业务错误 | | 4 | 网络错误或超时 | | 5 | 内部错误 |

命令

maptec geocode

地址 → 坐标。

| 选项 | 必填 | 说明 | |------|------|------| | --address <text> | 是 | 地址 | | --language <code> | 否 | 语言，如 en、zh-CN | | --region <code> | 否 | 地区偏向，如 SG、CN |

maptec geocode --address "Orchard Road" --language en --region SG --format json

maptec reverse-geocode

坐标 → 地址。

| 选项 | 必填 | 说明 | |------|------|------| | --lat <number> | 是 | 纬度 | | --lng <number> | 是 | 经度 | | --language <code> | 否 | 语言 | | --region <code> | 否 | 地区偏向 | | --result-type <types> | 否 | 结果类型过滤（| 分隔） | | --location-type <types> | 否 | 精度类型过滤 |

maptec reverse-geocode --lat 1.3048 --lng 103.8318 --language en --format json

maptec search text

关键词检索。

| 选项 | 必填 | 说明 | |------|------|------| | --query <text> | 是 | 关键词 | | --location <lng,lat> | 否 | 位置偏向：lng,lat 或 lng,lat,radius | | --language <code> | 否 | 语言（默认 en） | | --region <code> | 否 | 地区 | | --page-size <n> | 否 | 每页条数（默认 20） | | --type <category> | 否 | POI 类别 | | --rank <mode> | 否 | RELEVANCE | DISTANCE | POPULARITY |

maptec search text \
  --query "cafe" \
  --location "103.83,1.30,3000" \
  --language en \
  --region SG \
  --page-size 10 \
  --format json

maptec search nearby

周边检索。

| 选项 | 必填 | 说明 | |------|------|------| | --lat <number> | 是 | 圆心纬度 | | --lng <number> | 是 | 圆心经度 | | --radius <meters> | 否 | 半径，米（默认 500） | | --types <list> | 否 | POI 类型，逗号分隔 | | --limit <n> | 否 | 结果数量上限（默认 20） | | --language <code> | 否 | 语言（默认 en） | | --region <code> | 否 | 地区 | | --rank <mode> | 否 | 排序（默认 DISTANCE） |

maptec search nearby \
  --lat 1.3048 \
  --lng 103.8318 \
  --radius 1000 \
  --types "restaurant,cafe" \
  --limit 10 \
  --format json

maptec search suggest

输入提示。

| 选项 | 必填 | 说明 | |------|------|------| | --query <text> | 是 | 输入文本 | | --location <lng,lat> | 否 | 位置偏向 | | --language <code> | 否 | 语言（默认 en） | | --region <code> | 否 | 地区 | | --limit <n> | 否 | 结果数量上限（默认 20） |

maptec search suggest --query "Orch" --location "103.83,1.30" --limit 5 --format json

maptec search place

地点详情。

| 选项 | 必填 | 说明 | |------|------|------| | --id <placeId> | 是 | 地点 ID | | --language <code> | 否 | 语言 | | --region <code> | 否 | 地区 | | --session-token <token> | 否 | 会话令牌 |

maptec search place --id "<placeId>" --language en --format json

maptec route driving / maptec route truck

路线规划。起终点任选一种写法：

• --from / --to：地址、lng,lat 或 place ID
• --from-lat + --from-lng / --to-lat + --to-lng：坐标分量

文本地址会自动进行地理编码。

| 选项 | 说明 | |------|------| | --strategy <name> | fastest | shortest | eco | balanced | | --language <code> | 导航语言 | | --height <meters> | 车高（仅 truck） | | --weight <tons> | 总重（仅 truck） | | --length <meters> | 车长（仅 truck） |

默认输出 distance、duration、summary。需要路径几何时增加 --fields polyline。

可选字段：distance、duration、summary、polyline、warnings、legs。

maptec route driving \
  --from "Orchard Road" \
  --to "North Bridge Rd" \
  --fields distance,duration,summary \
  --format json

maptec route driving \
  --from-lat 1.2966 --from-lng 103.7764 \
  --to-lat 1.3048 --to-lng 103.8318 \
  --strategy fastest \
  --format json

maptec route truck \
  --from "103.85,1.29" \
  --to "103.83,1.30" \
  --height 4.2 \
  --weight 10 \
  --length 12 \
  --fields distance,duration,summary \
  --format json

示例

# 将结果写入文件
maptec geocode --address "Orchard Road" --region SG --format json --out result.json

# 检索后查询地点详情
maptec search suggest --query "Orchard" --limit 1 --format json
maptec search place --id "<placeId>" --format json

# 人类可读配置
maptec config get --format table

License

MIT © 2026 Maptec