Routes API 计算路线时,会将您提供的路点和配置参数作为输入。然后,该 API 会返回一个响应,其中包含默认路线和一个或多个备选路线。
您的响应可以包含不同类型的路线和其他数据,具体取决于您请求的字段:
如需在响应中添加此信息 | 请参阅此文档 |
---|---|
根据车辆的发动机类型显示最省油或最节能的路线。 | 配置环保路线 |
最多三条备选路线 | 请求备用路线 |
整个路线、路线的每个航段以及航段的每个步骤的多段线。 | 请求路线多段线 |
估算的过路费,已考虑到驾驶员或车辆可享受的所有过路费折扣或通行卡。 | 计算过路费 |
按语言代码和衡量单位(英制或公制)本地化的响应。 | 请求本地化的值 |
如需将导航说明的格式设置为 HTML 文本字符串,请将 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 添加到 extraComputations 。 |
额外计算 |
如需查看输入选项的完整列表,请参阅可用的路线选项和请求正文。
您可以根据响应,为客户提供根据其需求选择合适路线所需的信息。
关于字段掩码
调用方法来计算路线时,您必须指定一个字段掩码,用于定义您希望在响应中返回哪些字段。没有返回字段的默认列表。如果您省略此列表,这些方法会返回错误。
本文档中的示例显示了整个响应对象,而未考虑字段掩码。在生产环境中,您的响应将仅包含您在字段掩码中明确指定的字段。
如需了解详情,请参阅选择要返回的信息。
关于显示版权信息
向用户显示结果时,您必须添加以下版权声明:
Powered by Google, ©YEAR Google
例如:
Powered by Google, ©2023 Google
路线、路段和步骤简介
在查看 Routes API 返回的响应之前,您应该先了解路线的组成部分:
您的响应可能包含以下各个路线组成部分的相关信息:
路线:从起始路点经过任何中间路点到达目的地路点的整个行程。路线由一个或多个路程组成。
航段:路线中从一个航点到下一个航点的路径。每段路程都包含一个或多个离散的路段。
路线包含从每个航点到下一个航点的路径的单独路段。例如,如果路线包含单个起点航点和单个目的地航点,则路线包含单个航段。对于您在起点和目的地之后添加到路线中的每个额外航点(称为中继航点),该 API 都会添加单独的航段。
该 API 不会为穿行中间航点添加行程。例如,包含起点航点、穿行中继航点和目的地航点的路线仅包含一条从起点到目的地的路段,且会经过该航点。如需详细了解传递航点,请参阅定义直通航点。
步骤:路线路段中的单个指令。分段是路线的最基本单位。例如,某个步骤可以指示“在 Main Street 上向左转”。
响应中的内容
表示 API 响应的 JSON 对象包含以下顶级属性:
routes
,一个包含 Route 类型元素的数组。routes
数组包含 API 返回的每条路线的一个元素。该数组最多可包含 5 个元素:默认路线、环保路线,以及最多 3 条备选路线。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 |
I 表示备选路线。 |
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 Code 的每个位置(出发地、目的地或中间航点),API 会尝试查找具有对应地点 ID 的最相关位置。geocodingResults
数组的每个元素都包含一个 placeID
字段,其中包含作为地点 ID 的位置信息,以及一个 type
字段,用于指定位置类型,例如 street_address
、premise
或 airport
。
geocodingResults
数组包含三个字段:
origin
:该出发地的地点 ID(如果指定为地址字符串或 Plus 代码)。否则,响应中会省略此字段。destination
:如果目标位置是作为地址字符串或 Plus Code 指定的,则为目标位置的地点 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
方法默认采用“英语(美国)”语言和公制单位。