高德开放平台调用手册

规划驾车路线并读取耗时

调用路径规划 2.0 的 v5 驾车接口,取得推荐路线距离、预计耗时及可绘制的路段坐标。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 已具备 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 的终端。按调用步骤保存代码文件,再在同一终端执行。

调用步骤

  1. 01

    注册并完成适用的开发者认证;在控制台应用管理创建应用,添加 Key,服务平台选择 Web 服务。

  2. 02

    先判断个人研究学习或商业用途。商业项目办理适用技术服务许可;确认免费期、LBS 服务组月配额和当前服务 QPS。

  3. 03

    在服务器设置 AMAP_KEY,按实际出口 IP 配置白名单。本页最小例子面向仅 Key + IP 白名单的调用;如果已启用数字签名,须另外按官方规则计算并附带 sig。

  4. 04

    准备公开的测试地址或高德 GCJ-02 坐标;经度在前、纬度在后,坐标小数不超过 6 位。不要直接混入 GPS 或百度坐标。

  5. 05

    把经过地址解析或坐标转换的起终点填入 AMAP_ORIGIN 和 AMAP_DESTINATION;若位置在建筑内,按业务情况核对入口与道路。

  6. 06

    请求 show_fields=cost,polyline,成功后查看 route.paths 数组;distance 的单位是米,cost.duration 的单位是秒。

调用 01

获取高德推荐驾车路线

采用 v5/direction/driving 与 strategy=32,明确请求 cost 与 polyline 扩展,避免把 v3 的返回字段直接用于 v5。

GEThttps://restapi.amap.com/v5/direction/driving?key=${AMAP_KEY}&origin=${AMAP_ORIGIN}&destination=${AMAP_DESTINATION}&strategy=32&show_fields=cost,polyline&output=json

请求头

Accept
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
keyQuerystring必填Web 服务类型 Key。
origin / destinationQuerystring必填起终点经度,纬度,高德 GCJ-02 坐标,小数点后不超过 6 位。
strategyQueryinteger可选32 为默认高德推荐;33 避拥堵、34 高速优先等策略需按官方枚举选择,不能混用旧版 strategy 语义。
show_fieldsQuerystring可选用逗号选择返回的扩展类型;本例 cost(耗时与费用)和 polyline(路段点串),不传时只有基础字段。
plateQuerystring可选用于限行判断的车牌信息;本例不传,实际项目按适用规则与用户授权配置。
outputQuerystring可选v5 驾车当前文档为 JSON,本例 json。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 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"
Python 3
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
// 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 字段。 以下为结构示意,非本站实测结果。

JSON
{
  "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;返回结构示意不是实际定位或路况结果。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
    创建 Web 服务类型 Key核验日期 2026-10-15
  2. 02
  3. 03
  4. 04
    高德使用 GCJ-02 坐标核验日期 2026-10-15
  5. 05
    非高德坐标的转换 API核验日期 2026-10-15
  6. 06
  7. 07
    Web 服务 infocode 错误码核验日期 2026-10-15

高德开放平台的其他调用手册

← 返回高德开放平台的全部功能