Routes API 计算路线时,会使用您作为输入提供的航点和配置参数。然后,API 会返回一个包含 default 路由以及一个或多个备用路由的响应。
您的响应可以包含不同类型的路由和其他数据,具体取决于您请求的字段:
将其包含在响应中 | 请参阅此文档 |
---|---|
根据车辆的引擎类型,最省油或最节能的路线。 | 配置环保路线 |
最多三条备选路线 | 请求备选路线 |
整条路线、路线的每一个路程和一段路程的多段线。 | 请求路线多段线 |
预估的通行费,将驾驶员或车辆可用的通行费折扣或卡券考虑在内。 | 计算通行费 |
按语言代码和度量单位(英制或公制)提供的本地化响应。 | 请求本地化的值 |
如需将导航指示设置为 HTML 文本字符串,请将 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 添加到 extraComputations 。 |
额外计算 |
如需查看输入选项的完整列表,请参阅可用的路由选项和请求正文。
使用响应,您可以为客户提供必要的信息,根据他们的要求选择合适路线。
关于字段掩码
调用方法计算路线时,您必须指定字段掩码,以定义您想要在响应中返回的字段。没有默认的返回字段列表。如果省略此列表,这些方法会返回错误。
本文档中的示例展示的是不考虑字段掩码的整个响应对象。在生产环境中,您的响应只会包含您在字段掩码中明确指定的字段。
有关详情,请参阅选择要返回的信息。
关于显示版权
在向您的用户显示这些结果时,您必须加上以下版权声明:
Powered by Google, ©YEAR Google
例如:
Powered by Google, ©2023 Google
关于路线、路程和步数
在查看 Routes API 返回的响应之前,您应该了解路由的组成部分:
您的响应可能包含每个路线组成部分的相关信息:
路线:从出发地航点经过任何中间航点,到目的地航点的整个行程。路线由一段或多段路程组成。
路程:从路线中的一个航点到路线中下一个航点的路径。每段路程均由一个或多个离散的“步数”组成。
路线包含用于从每个航点到下一个航点的路径的一段单独的路程。例如,如果路线包含一个出发地航点和一个目的地航点,则该路线包含一段路程。对于您添加到路线的起点和目的地之后每增加一个航点(称为“中间航点”),API 会添加一段单独的路程。
该 API 不会为“直通”中间航点添加路程。例如,一条路线包含出发地航点、直通中间航点和目的地航点,在途经航点时仅包含从出发地到目的地的一段路程。如需详细了解直通航点,请参阅定义直通航点。
路段:沿路线路程的单个说明。路段是路线的最小单位。例如,路段可能表示“在主街左转”。
响应中的内容
表示 API 响应的 JSON 对象包含以下顶级属性:
routes
,Route 类型的元素数组。routes
数组包含 API 返回的每条路线的一个元素。该数组最多可包含五个元素:默认路线、环保路线和最多三条备选路线。geocodingResults
,一个类型为 GeocodingResults 的元素数组。对于您指定为地址字符串或 Plus 代码的请求中的每个位置(出发地、目的地或中间航点),API 会执行地点 ID 查找。此数组的每个元素都包含与某个营业地点对应的地点 ID。请求中指定为地点 ID 或纬度/经度坐标的位置不包括在内。如果您已使用地点 ID 或经纬度坐标指定了所有位置,则不会提供此数组。fallbackInfo
,类型为 FallbackInfo。如果 API 无法从所有输入属性计算路线,则可能会回退到使用其他计算方法。使用回退模式时,此字段包含有关回退响应的详细信息。否则,将取消设置此字段。
响应的格式如下:
{ // The routes array. "routes": [ { object (Route) } ], // The place ID lookup results. "geocodingResults": [ { object (GeocodedWaypoint) } ], // The fallback property. "fallbackInfo": { object (FallbackInfo) } }
解密路由数组
响应包含 routes
数组,其中每个数组元素都是 Route 类型。每个数组元素表示从起点到目的地的完整路线。API 始终返回至少一个路由,称为默认路由。
您可以请求其他路由。如果您请求环保路线,则该数组可以包含两个元素:默认路线和环保路线。或者,在请求中将 computeAlternativeRoutes
设置为 true
,以便为响应添加最多三条备用路由。
该数组中的每条路线均使用 routeLabels
数组属性进行标识:
值 | 说明 |
---|---|
DEFAULT_ROUTE |
标识默认路由。 |
FUEL_EFFICIENT |
识别环保路线。 |
DEFAULT_ROUTE_ALTERNATE |
表示备选路线。 |
legs
数组包含路线每段路程的定义。其余属性(如 distanceMeters
、duration
和 polyline,
)包含有关该路由整体的信息:
{ "routeLabels": [ enum (RouteLabel) ], "legs": [ { object (RouteLeg) } ], "distanceMeters": integer, "duration": string, "routeLabels": [string], "staticDuration": string, "polyline": { object (Polyline) }, "description": string, "warnings": [ string ], "viewport": { object (Viewport) }, "travelAdvisory": { object (RouteTravelAdvisory) } "routeToken": string }
根据当前驾驶条件和其他因素,默认路线和环保路线可以相同。在本例中,routeLabels
数组包含 DEFAULT_ROUTE
和 FUEL_EFFICIENT
这两个标签。
{ "routes": [ { "routeLabels": [ "DEFAULT_ROUTE", "FUEL_EFFICIENT" ], … } ] }
了解 legs 数组
响应中的每个 route
都包含一个 legs
数组,其中每个 legs
数组元素都是 RouteLeg 类型。数组中的每段路程均用于定义从路线上的一个航点到下一个航点的路径。路线始终包含至少一段路程。
legs
属性包含 steps
数组中沿路程的每个路段的定义。其余属性(如 distanceMeters
、duration
和 polyline
)包含有关路程的信息。
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "steps": [ { object (RouteLegStep) } ], "travelAdvisory": { object (RouteLegTravelAdvisory) } }
了解步数数组
响应中的每段路程都包含一个 steps
数组,其中每个 steps
数组元素都是 RouteLegStep 类型。路段对应路程上的一条指令。路程通常至少包含一个路段。
steps
数组中的每个元素都包含类型为 NavigationInstruction 的 navigationInstruction
属性,该属性包含步骤指令。例如:
"navigationInstruction": { "maneuver": "TURN_LEFT", "instructions": "Turn left toward Frontage Rd" }
instructions
可能包含有关该步骤的更多信息。例如:
"navigationInstruction": { "maneuver": "TURN_SLIGHT_LEFT", "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days" }
该步骤中的其余属性描述该步骤的相关信息,例如 distanceMeters
、duration
和 polyline
:
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "navigationInstruction": { object (NavigationInstruction) } }
指定步骤说明的语言
如有必要,该 API 会以本地语言返回路线信息,并音译为用户可以阅读的脚本,同时遵循首选语言。地址组成部分均以同一种语言返回。
使用请求的
languageCode
参数从支持的语言列表中明确设置路线语言。Google 会经常更新支持的语言,因此该列表可能并非详尽无遗。如果某个名称在指定语言中不可用,则 API 会使用最接近的匹配项。
指定的语言可以影响 API 选择返回的结果集以及返回顺序。地理编码器会根据语言对缩写进行不同的解读,例如街道类型的缩写,或者可能在一种语言中有效但在另一种语言中无效的同义词。例如,在匈牙利语中,utca 和 tér 是街道的同义词。
了解 GeocodingResults 数组
对于请求中指定为地址字符串或 Plus 代码的每个位置(出发地、目的地或中间航点),API 会尝试查找具有相应地点 ID 的最相关位置。geocodingResults
数组的每个元素均包含 placeID
字段(包含以地点 ID 表示的位置)和 type
字段(用于指定位置类型,例如 street_address
、premise
或 airport
)。
geocodingResults
数组包含三个字段:
origin
:如果以地址字符串或 Plus 代码的形式指定,则表示出发地的地点 ID。否则,响应中将省略此字段。destination
:如果以地址字符串或 Plus 代码的形式指定,则表示目的地的地点 ID。否则,响应中将省略此字段。intermediates
:一个数组,其中包含以地址字符串或 Plus 代码形式指定的任何中间航点的地点 ID。如果您使用地点 ID 或纬度和经度坐标指定中间航点,响应中将省略该值。使用响应中的intermediateWaypointRequestIndex
属性来确定请求中的哪个中间航点对应于响应中的地点 ID。
"geocodingResults": { "origin": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "destination": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "intermediates": [ { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string }, { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string } ] }
了解本地化响应值
本地化响应值是一个额外的响应字段,用于为返回的参数值提供本地化文本。提供行程时长、距离和单位制(公制或英制)的本地化文本。您可以使用字段掩码请求本地化值,并且可以指定语言和单位制,也可以使用 API 推断的值。如需了解详情,请参阅 LocalizedValues。
例如,如果您指定德语 (de) 和英制单位的语言代码,则得到的 distanceMeters
值为 49889.7,但也会获得本地化文本,同时提供以德语和英制单位表示的距离测量结果,因此也就是“31 Meile”。
以下是您将看到的本地化值的示例:
{ "localized_values": { "distance": { "text": "31,0 Meile/n" }, "duration": { "text": 38 Minuten}. "static_duration": { "text": 36 Minuten}. } }
如果您未指定语言或单位制,则 API 会通过以下方式推断语言和单位:
ComputeRoutes
方法会根据出发地航点推断位置和距离单位。因此,对于美国境内的路由请求,API 会推断出en-US
语言和IMPERIAL
单位。ComputeRouteMatrix
方法默认采用“en-US”语言和 METRIC 单位。