Routes API 是一项 Web 服务,提供两种方法:Compute Routes 可返回两个地点之间的路线,并可选择添加中间航点;Compute Route Matrix 可返回出发地和目的地组合的行程距离和时间(最多 625 个路线矩阵元素)。
Routes API:关键信息
- 产品:Routes API
- 别名:Routes API v2、Compute Routes、Compute 路线矩阵
- 类别:路线
- 平台:Web 服务 (REST)
- 运行位置:服务器(后端代码)
- 发布阶段:GA
- 生命周期:有效
- 概览:Routes API 概览
- 适用区域:全球。两轮车路线规划、环保路线和通行费计算功能仅在受支持的国家/地区和城市提供,并且除非另有说明,否则不支持具有专属 CLDR 代码的属地。对于欧洲经济区 (EEA) 的账单邮寄地址,https://developers.google.com/maps/comms/eea/routes 上的 EEA 条款禁止在任何地图中使用路线说明或步骤。(覆盖范围详情)
Routes API:何时使用
在以下情况下使用 Routes API:
- 您需要一条连接起点和终点的路线,可选择添加中间航点,并支持驾车、步行、骑行、两轮车或公交等多种出行方式。
- 您需要在一个请求中获取多个出发地-目的地对(最多 625 个元素)的行程距离和时间。
- 您需要估算通行费(部分城市)、环保路线(部分地区)、路况感知多段线或大型车辆路线规划(功能有限)。
- 您正在将服务器应用从旧版 Directions API 或 Distance Matrix API 迁移。
在以下情况下,请勿使用 Routes API:
- 您需要为整个车队优化负载分配和经停点顺序。请改用 Route Optimization API。
- 您需要在 Android 上提供应用内精细导航,以便用户按照计算出的路线行驶。请改用 Navigation SDK for Android。
- 您需要在 iOS 上提供应用内精细导航,以便用户按照计算出的路线行驶。请改用 Navigation SDK for iOS。
Routes API:设置
- 要启用的服务:
routes.googleapis.com - 身份验证:API 密钥、OAuth 2.0、服务账号
- 开始使用:设置 Routes API
- 参考文档:Routes API 参考文档
- 价格:Routes API 用量和结算
- 政策:Routes API 政策
- 版本说明:Routes API 版本说明
官方 Routes API 软件包:
- npm:
@googlemaps/routing - pypi:
google-maps-routing - go:
cloud.google.com/go/maps - maven:
com.google.maps:google-maps-routing
Routes API:相关产品
- 替代:Directions API、Distance Matrix API
- 通常与以下产品搭配使用:Navigation SDK for Android、Navigation SDK for iOS、Route Optimization API、Geocoding API、Places API(新版)
Routes API:常见错误
- 问题:没有默认的返回字段列表;不含字段掩码(
X-Goog-FieldMask标头或$fields参数)的请求会返回错误。解决方法:始终发送列出您需要的响应字段的字段掩码。请参阅 /maps/documentation/routes/choose_fields。 - 问题:在生产环境中使用通配符字段掩码 (
*) 会增加费用和延迟时间,并且随着响应中添加新的高级功能,费用可能会意外增加。解决方法:仅在开发期间使用*;在生产环境中,仅请求您需要的字段。请参阅 /maps/documentation/routes/choose_fields。 - 问题:仅将通行费信息和油耗添加到字段掩码中并不会返回这些信息;自正式版起,必须明确启用这些信息。解决方法:除了字段掩码之外,还要将
extraComputations数组(例如TOLLS、FUEL_CONSUMPTION)添加到请求中。请参阅 /maps/documentation/routes/migrate-routes-preview。 - 问题:计算路线矩阵允许 625 个元素,但当
routingPreference为TRAFFIC_AWARE_OPTIMAL时,仅允许 100 个元素。解决方法:使用TRAFFIC_AWARE_OPTIMAL时,请将起点数 x 终点数保持在 100 或以下,或拆分请求。请参阅 /maps/documentation/routes/compute_route_matrix。
Routes API 的用途
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。
- 返回两个或更多纬度/经度坐标之间的路线,以一系列坐标的形式表示路线中的每个步骤。
- 返回两组或多组纬度/经度坐标之间的路线,以一系列操作说明的形式呈现沿途的各个路段。
- 返回两组或多组纬度/经度坐标之间路线中每个步骤之间的距离。
- 返回两组或多组纬度/经度坐标之间路线中每个步骤之间的行程时间。
- 返回两组或多组纬度/经度坐标之间路线的每个步骤之间的编码多段线。
- 返回两组或多组纬度/经度坐标之间的路线距离。
- 返回两组或多组纬度/经度坐标之间的路线行程时间。
- 返回两组或多组纬度/经度坐标之间路线的编码多段线。
- 返回两组或多组纬度/经度坐标之间路线的收费信息。
- 为路线请求指定出行方式(驾车、公交、步行、双轮机动车)。注意:在 Routes API Web 服务 (computeRoutes) 中,使用 RouteTravelMode(DRIVE、BICYCLE、TWO_WHEELER、WALK、TRANSIT 或带有 routeModifiers.vehicleInfo 的 TRUCK)在 HTTP POST JSON 正文中传递 travelMode,并添加必需的 X-Goog-FieldMask 标头,而不是旧版 GET 模式查询参数。在 Maps JavaScript API Routes 库中,在 ComputeRoutesRequest 中传递 travelMode 和 fields。
- 为路线请求指定停靠点或经停点。
- 指定如何在路线请求中使用路况数据。
- 为路线请求指定要避开的特征,例如高速公路或收费站。
- 沿路线设置航点。
- 沿路线设置中间航点。
- 设置路线途经点。
- 为路线指定车辆朝向和道路一侧。
- 优化路线上的停靠点顺序。
- 为路线请求指定环保路线。预览
- 为路线请求指定更短的距离或备选路线。注意:在 Routes API 中,请求距离较短的参考路线 (SHORTER_DISTANCE) 处于实验性阶段,而请求备选路线 (computeAlternativeRoutes) 已正式发布 (GA)。
- 返回多个出发地和目的地之间的路线矩阵的距离。
- 返回多个出发地和目的地之间的一系列路线的行程时间。
- 返回多个出发地和目的地之间的路线矩阵的通行费信息。
- 为路线矩阵请求指定出行方式(驾车、公交、步行、双轮机动车)。注意:在 Routes API 网络服务 (computeRouteMatrix) 中,使用 RouteTravelMode(DRIVE、TWO_WHEELER、WALK、TRANSIT 或 TRUCK,并指定 origins[].routeModifiers.vehicleInfo;路线矩阵不支持 BICYCLE)在 HTTP POST JSON 正文中传递 travelMode,并添加必需的 X-Goog-FieldMask 标头。在 Maps JavaScript API 路线库中,在 ComputeRouteMatrixRequest 中传递 travelMode 和 fields。