规划驾车路线并读取耗时
调用路径规划 2.0 的 v5 驾车接口,取得推荐路线距离、预计耗时及可绘制的路段坐标。
← 返回平台功能接入准备
- 已具备 Web 服务 Key、对应接口权限和适用用途许可;有足够 LBS 服务组月配额及 QPS。
- 起终点均为官方服务支持范围内的 GCJ-02 坐标;本页不覆盖实时逐向导航 SDK 或货车专用算路。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。
AMAP_KEY- 控制台应用管理中创建的 Web 服务类型 Key,仅在本地或服务器使用,不能使用 JS API / Android / iOS Key。
AMAP_ORIGIN- 起点 GCJ-02 高德坐标,经度在前;此处为公开示例坐标,按实际位置替换。
AMAP_DESTINATION- 终点 GCJ-02 高德坐标,经度在前;GPS / 百度坐标应先使用官方转换接口。
export AMAP_KEY='replace_with_your_web_service_key'
export AMAP_ORIGIN='116.481028,39.989643'
export AMAP_DESTINATION='116.434446,39.908160'以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件,再在同一终端执行。
调用步骤
- 01
注册并完成适用的开发者认证;在控制台应用管理创建应用,添加 Key,服务平台选择 Web 服务。
- 02
先判断个人研究学习或商业用途。商业项目办理适用技术服务许可;确认免费期、LBS 服务组月配额和当前服务 QPS。
- 03
在服务器设置 AMAP_KEY,按实际出口 IP 配置白名单。本页最小例子面向仅 Key + IP 白名单的调用;如果已启用数字签名,须另外按官方规则计算并附带 sig。
- 04
准备公开的测试地址或高德 GCJ-02 坐标;经度在前、纬度在后,坐标小数不超过 6 位。不要直接混入 GPS 或百度坐标。
- 05
把经过地址解析或坐标转换的起终点填入 AMAP_ORIGIN 和 AMAP_DESTINATION;若位置在建筑内,按业务情况核对入口与道路。
- 06
请求 show_fields=cost,polyline,成功后查看 route.paths 数组;distance 的单位是米,cost.duration 的单位是秒。
获取高德推荐驾车路线
采用 v5/direction/driving 与 strategy=32,明确请求 cost 与 polyline 扩展,避免把 v3 的返回字段直接用于 v5。
https://restapi.amap.com/v5/direction/driving?key=${AMAP_KEY}&origin=${AMAP_ORIGIN}&destination=${AMAP_DESTINATION}&strategy=32&show_fields=cost,polyline&output=json请求头
Acceptapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
keyQuery | string必填 | Web 服务类型 Key。 |
origin / destinationQuery | string必填 | 起终点经度,纬度,高德 GCJ-02 坐标,小数点后不超过 6 位。 |
strategyQuery | integer可选 | 32 为默认高德推荐;33 避拥堵、34 高速优先等策略需按官方枚举选择,不能混用旧版 strategy 语义。 |
show_fieldsQuery | string可选 | 用逗号选择返回的扩展类型;本例 cost(耗时与费用)和 polyline(路段点串),不传时只有基础字段。 |
plateQuery | string可选 | 用于限行判断的车牌信息;本例不传,实际项目按适用规则与用户授权配置。 |
outputQuery | string可选 | v5 驾车当前文档为 JSON,本例 json。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
--request GET \
--url "https://restapi.amap.com/v5/direction/driving?key=${AMAP_KEY}&origin=${AMAP_ORIGIN}&destination=${AMAP_DESTINATION}&strategy=32&show_fields=cost,polyline&output=json" \
--header "Accept: application/json"
import json
import os
import re
import urllib.request
import urllib.error
def expand(value):
return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
lambda match: os.environ[match.group(1)], value)
url = expand("https://restapi.amap.com/v5/direction/driving?key=${AMAP_KEY}&origin=${AMAP_ORIGIN}&destination=${AMAP_DESTINATION}&strategy=32&show_fields=cost,polyline&output=json")
headers = {
"Accept": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "status" in result and result["status"] != "1":
raise SystemExit("平台返回业务错误,请结合下方排错说明检查响应")
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
return process.env[name];
});
}
const url = expand("https://restapi.amap.com/v5/direction/driving?key=${AMAP_KEY}&origin=${AMAP_ORIGIN}&destination=${AMAP_DESTINATION}&strategy=32&show_fields=cost,polyline&output=json");
const headers = Object.fromEntries(
Object.entries({
"Accept": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
method: "GET",
headers,
signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "status") && result["status"] !== "1") {
throw new Error('平台返回业务错误,请结合下方排错说明检查响应');
}
返回示例
按官方 v5 字段整理的结构示意,距离、耗时、道路名、路径点和费用均为虚构,不能用于实际导航,未进行真实接口实测。耗时来自请求的 cost 扩展,不是路径对象直接的 duration 字段。 以下为结构示意,非本站实测结果。
{
"status": "1",
"info": "OK",
"infocode": "10000",
"count": "1",
"route": {
"origin": "116.481028,39.989643",
"destination": "116.434446,39.908160",
"paths": [
{
"distance": "1200",
"restriction": "0",
"cost": {
"duration": "240",
"tolls": "0",
"toll_distance": "0"
},
"steps": [
{
"instruction": "沿示例道路行驶",
"orientation": "西",
"road_name": "示例道路",
"step_distance": "1200",
"polyline": "116.481028,39.989643;116.482028,39.989643"
}
]
}
]
}
}常见错误与排查
10001 INVALID_USER_KEYKey 不正确或已过期。- 核对 AMAP_KEY 与控制台状态;不要把应用名称、其他平台 Key 当成 Web 服务 Key。
10009 USERKEY_PLAT_NOMATCHKey 类型与请求平台不符。- 重新选择 Web 服务类型 Key,不能用 JavaScript API Key 调 REST 服务。
10005 INVALID_USER_IP请求服务器出口 IP 不在白名单。- 检查实际公网出口 IP,更新控制台白名单;本地开发与生产主机可能不是同一出口。
10007 INVALID_USER_SIGNATURE启用了数字签名但 sig 未按规则生成。- 按 Key 控制台签名设置与官方算法生成 sig;只设置 Key 的本页最小示例不适用于已强制签名的配置。
10019 / 10020 / 10021服务、Key 或账号维度的 QPS 超限。- 降低并发并排队,检查账号下其他 Key 的共同用量;确需扩容时单独购买服务 QPS。
40000 QUOTA_PLAN_RUN_OUT所购服务余额耗尽。- 核对当前服务组配额、流量包及有效期,需要时购买额度;增加 Key 不会复制账号配额。
20800 / 20011规划点超出相应服务范围,或缺少海外权限。- 检查经纬度顺序和坐标系,确认目标区域的服务与许可;不要通过反复请求扩大服务范围。
20801 NO_ROADS_NEARBY规划点附近找不到道路。- 核对地址解析精度、入口和地图点位,不要随意移动用户坐标后声称结果精确。
20802 ROUTE_FAIL路线计算失败,可能与道路连通有关。- 核对起终点、跨区域或路线条件;保留请求参数和错误码后提交官方工单。
调用注意
- 预计耗时、收费与交通信息可能变化。restriction=0 表示未限行或已规避,不是对所有车辆、时段与政策的通行保证。
- v5 的路段字段为 road_name、step_distance;polyline 为经纬度点串,路段间点串可按顺序用于自己的地图展示,但展示与数据使用仍受服务条款约束。
- 本例参数较短使用 GET;官方说明参数过长导致请求失败时需改 POST,不能不加区分地复用这里的 GET 例子处理长途经点。
注意事项
- 地理编码、逆地理编码、基础路线和坐标转换共享基础 LBS 服务组配额;本例运行会消耗实际调用量。
- 个人非商业免费额度不是永久免费:公开价格页限定为自注册认证起 1 年;商业许可、超额流量和 QPS 另行核算。
- 示例只展示请求及字段读取。HTTP 2xx 后仍要检查 status、info 与 infocode;返回结构示意不是实际定位或路况结果。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01创建 Web 服务类型 Key核验日期 2026-10-15
- 02服务组月配额、调用价和技术服务许可核验日期 2026-10-15
- 03个人研究学习与商业用途许可条件核验日期 2026-10-15
- 04高德使用 GCJ-02 坐标核验日期 2026-10-15
- 05非高德坐标的转换 API核验日期 2026-10-15
- 06路径规划 2.0 驾车请求与返回字段核验日期 2026-10-15
- 07Web 服务 infocode 错误码核验日期 2026-10-15
