- HTTP 请求
- 请求正文
- 响应正文
- PolylineQuality
- PolylineEncoding
- 单位
- ReferenceRoute
- ExtraComputation
- 路线
- RouteLabel
- RouteLeg
- 多段线
- RouteLegStep
- NavigationInstruction
- 动作
- RouteLegStepTravelAdvisory
- RouteLegStepLocalizedValues
- RouteLegStepTransitDetails
- TransitStopDetails
- TransitStop
- TransitDetailsLocalizedValues
- LocalizedTime
- TransitLine
- TransitAgency
- TransitVehicle
- TransitVehicleType
- RouteLegTravelAdvisory
- RouteLegLocalizedValues
- StepsOverview
- MultiModalSegment
- 视口
- RouteLocalizedValues
- GeocodingResults
- GeocodedWaypoint
根据一组终点和中间航点,返回主路线和可选备选路线。
注意:此方法要求您在输入中指定响应字段掩码。您可以使用网址参数 $fields
或 fields
,或使用 HTTP/gRPC 标头 X-Goog-FieldMask
提供响应字段掩码(请参阅可用的网址参数和标头)。该值是以英文逗号分隔的字段路径列表。请参阅有关如何构建字段路径的详细文档。
例如,在此方法中:
- 所有可用字段的字段掩码(用于手动检查):
X-Goog-FieldMask: *
- 路线级时长、距离和多段线(生产环境设置示例)的字段掩码:
X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
Google 不建议使用通配符 (*
) 响应字段掩码或在顶级 (routes
) 指定字段掩码,因为:
- 仅选择您需要的字段可帮助我们的服务器节省计算周期,从而以更短的延迟时间将结果返回给您。
- 仅选择生产作业中需要的字段,可确保稳定的延迟性能。我们未来可能会添加更多响应字段,这些新字段可能需要额外的计算时间。如果您选择所有字段,或者选择顶层的所有字段,则效果可能会下降,因为我们添加的所有新字段都会自动包含在响应中。
- 仅选择所需字段可以降低响应大小,从而提高网络吞吐量。
HTTP 请求
POST https://routes.googleapis.com/directions/v2:computeRoutes
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "origin": { object ( |
字段 | |
---|---|
origin |
必需。出发地航点。 |
destination |
必需。目的地航点。 |
intermediates[] |
可选。沿路线的一组航点(不包括终点),用于在经停点或经过。最多支持 25 个中间航点。 |
travelMode |
可选。指定交通方式。 |
routingPreference |
可选。指定如何计算路由。服务器尝试使用所选路由偏好设置来计算路由。如果路由偏好设置导致错误或延迟时间过长,则会返回错误。只有在 |
polylineQuality |
可选。指定您对多段线质量的偏好。 |
polylineEncoding |
可选。指定多段线的首选编码。 |
departureTime |
可选。出发时间。如果未设置此值,则此值默认为您发出请求的时间。注意:当 时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例: |
arrivalTime |
可选。到达时间。注意:只能在 时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例: |
computeAlternativeRoutes |
可选。指定是否除了路由之外,还计算备选路由。系统不会为包含中间航点的请求返回备选路线。 |
routeModifiers |
可选。一组要满足的,会影响路线计算方式的条件。 |
languageCode |
可选。BCP-47 语言代码,例如“en-US”或“sr-Latn”。如需了解详情,请参阅 Unicode 语言区域标识符。如需查看受支持语言的列表,请参阅语言支持。如果您未提供此值,系统会根据路线请求的位置推断显示语言。 |
regionCode |
可选。地区代码,指定为 ccTLD(“顶级域名”)双字符值。如需了解详情,请参阅国家/地区代码顶级域名。 |
units |
可选。指定显示字段的度量单位。这些字段包括 |
optimizeWaypointOrder |
可选。如果设置为 true,该服务会尝试对指定的中间航点重新排序,从而最大限度地降低路线的总体成本。如果任何中间航点是 |
requestedReferenceRoutes[] |
可选。指定除了默认路由之外,要将哪些引用路由作为请求的一部分进行计算。参考路线是指路线计算目标与默认路线不同的路线。例如, |
extraComputations[] |
可选。可用于完成请求的额外计算的列表。注意:这些额外计算可能会在响应中返回额外字段。还必须在字段掩码中指定这些 extra 字段,以便在响应中返回。 |
trafficModel |
可选。指定计算交通时间时要使用的假设条件。此设置会影响 |
transitPreferences |
可选。指定会影响为 |
响应正文
v2.computeRoutes 响应消息。
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 |
---|
{ "routes": [ { object ( |
字段 | |
---|---|
routes[] |
当您指定 |
fallbackInfo |
在某些情况下,如果服务器无法使用所有输入偏好设置计算路线结果,则可能会回退到使用其他的计算方式。使用回退模式时,此字段包含有关回退响应的详细信息。否则,将取消设置此字段。 |
geocodingResults |
包含以地址形式指定的路标的地理编码响应信息。 |
PolylineQuality
用于指定多段线质量的一组值。
枚举 | |
---|---|
POLYLINE_QUALITY_UNSPECIFIED |
未指定多段线质量偏好设置。默认为 OVERVIEW 。 |
HIGH_QUALITY |
指定优质多段线 - 由多于 OVERVIEW 的点组成,但响应大小会增加。如果您需要更高的精确度,请使用此值。 |
OVERVIEW |
指定总览多段线 - 该多段线由少量的点组成。显示路线概览时使用此值。与使用 HIGH_QUALITY 选项相比,使用此选项的请求延迟时间较短。 |
PolylineEncoding
指定要返回的多段线的首选类型。
枚举 | |
---|---|
POLYLINE_ENCODING_UNSPECIFIED |
未指定多段线类型偏好设置。默认为 ENCODED_POLYLINE 。 |
ENCODED_POLYLINE |
指定使用多段线编码算法进行编码的多段线。 |
GEO_JSON_LINESTRING |
使用 GeoJSON LineString 格式指定多段线 |
单位
一组值,用于指定显示中使用的度量单位。
枚举 | |
---|---|
UNITS_UNSPECIFIED |
未指定度量单位。默认值为根据请求推断出的度量单位。 |
METRIC |
公制度量单位。 |
IMPERIAL |
英制计量单位。 |
ReferenceRoute
ComputeRoutesRequest 上受支持的引用路由。
枚举 | |
---|---|
REFERENCE_ROUTE_UNSPECIFIED |
未使用。包含此值的请求将失败。 |
FUEL_EFFICIENT |
省油路线。标有此值的路线应根据油耗等参数进行优化。 |
ExtraComputation
完成请求时要执行的额外计算。
枚举 | |
---|---|
EXTRA_COMPUTATION_UNSPECIFIED |
未使用。包含此值的请求将失败。 |
TOLLS |
路线的收费信息。 |
FUEL_CONSUMPTION |
路线的预估耗油量。 |
TRAFFIC_ON_POLYLINE |
路线的路况感知多段线。 |
HTML_FORMATTED_NAVIGATION_INSTRUCTIONS |
NavigationInstructions ,以格式化的 HTML 文本字符串表示。此内容应按原样阅读,仅供显示之用。请勿以程序化方式解析该文件。 |
路由
包含一条路线,由一系列相连的路段组成,这些路段连接起点、终点和中间航点。
JSON 表示法 |
---|
{ "routeLabels": [ enum ( |
字段 | |
---|---|
routeLabels[] |
|
legs[] |
组成路线的一组路程(航点之间的路径段)。每段路程均对应于两个非 |
distanceMeters |
路线的行程距离(以米为单位)。 |
duration |
导航路线所需的时长。如果您将 时长以秒为单位,最多包含九个小数位,以“ |
staticDuration |
不考虑交通状况的情况下经过路线的行程时长。 时长以秒为单位,最多包含九个小数位,以“ |
polyline |
整个路线多段线。此多段线是所有 |
description |
路线的说明。 |
warnings[] |
显示路线时显示的一组警告。 |
viewport |
多段线的视口边界框。 |
travelAdvisory |
有关路线的其他信息。 |
optimizedIntermediateWaypointIndex[] |
如果您将 |
localizedValues |
|
routeToken |
一个可在网络上安全使用且采用 base64 编码的路线令牌,可以传递给 Navigation SDK,让 Navigation SDK 在导航期间能够重建路线,并在发生重新路线时,通过调用 v2.computeRoutes 在创建路线时遵循最初创建路线。客户应将此令牌视为不透明 blob。它不适用于读取或更改。注意: |
RouteLabel
的标签,有助于识别路线的特定属性,以便与其他路线属性进行比较。Route
枚举 | |
---|---|
ROUTE_LABEL_UNSPECIFIED |
默认值 - 未使用。 |
DEFAULT_ROUTE |
为路线计算返回的默认“最佳”路线。 |
DEFAULT_ROUTE_ALTERNATE |
默认“最佳”路由的替代方案。指定了 后,将返回此类路线。 |
FUEL_EFFICIENT |
省油路线。标有此值的路线应根据节能参数(如耗油量)进行优化。 |
RouteLeg
包含非 via
航点之间的路段。
JSON 表示法 |
---|
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object ( |
字段 | |
---|---|
distanceMeters |
路线路程的行程距离(以米为单位)。 |
duration |
导航路程所需的时长。如果 时长以秒为单位,最多包含九个小数位,以“ |
staticDuration |
通过路程的行程时长,计算时不考虑路况信息。 时长以秒为单位,最多包含九个小数位,以“ |
polyline |
此路程的总体多段线,其中包含每个 |
startLocation |
此路程的起始位置。此位置可能与提供的 |
endLocation |
此路程的结束位置。此位置可能与提供的 |
steps[] |
一组路段,用于表示此路程中的路段。每个路段代表一条导航指令。 |
travelAdvisory |
包含应通知用户的其他信息,例如路线路程可能的交通可用区限制。 |
localizedValues |
|
stepsOverview |
有关此 |
Polyline
封装编码多段线。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 polyline_type 。封装多段线的类型。默认为 coding_polyline。polyline_type 只能是下列其中一项: |
|
encodedPolyline |
使用多段线编码算法对多段线进行的字符串编码 |
geoJsonLinestring |
使用 GeoJSON LineString 格式指定多段线。 |
RouteLegStep
包含
的一个片段。一个路段对应一条导航指令。路线路程由路段组成。RouteLeg
JSON 表示法 |
---|
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object ( |
字段 | |
---|---|
distanceMeters |
此路段的行程距离(以米为单位)。在某些情况下,此字段可能没有值。 |
staticDuration |
不考虑路况条件的情况下经过此路段的行程时长。在某些情况下,此字段可能没有值。 时长以秒为单位,最多包含九个小数位,以“ |
polyline |
与此路段相关联的多段线。 |
startLocation |
此路段的起始位置。 |
endLocation |
此路段的结束位置。 |
navigationInstruction |
导航说明。 |
travelAdvisory |
包含应通知用户的其他信息,例如某路段可能设有交通拥堵区域的限制。 |
localizedValues |
|
transitDetails |
有关此步骤的详细信息(如果出行方式为 |
travelMode |
此路段使用的出行方式。 |
Maneuver
一组值,用于指定当前路段要执行的导航操作(例如左转、合并或直行)。
枚举 | |
---|---|
MANEUVER_UNSPECIFIED |
未使用。 |
TURN_SLIGHT_LEFT |
稍微向左转。 |
TURN_SHARP_LEFT |
向 左 转。 |
UTURN_LEFT |
左转调头。 |
TURN_LEFT |
向左转。 |
TURN_SLIGHT_RIGHT |
请稍微向右转。 |
TURN_SHARP_RIGHT |
向右转。 |
UTURN_RIGHT |
右转调头。 |
TURN_RIGHT |
向右转。 |
STRAIGHT |
直奔主题。 |
RAMP_LEFT |
走左侧坡道。 |
RAMP_RIGHT |
请走右侧坡道。 |
MERGE |
合并到流量。 |
FORK_LEFT |
拿左叉子。 |
FORK_RIGHT |
使用右边的叉子。 |
FERRY |
坐轮渡。 |
FERRY_TRAIN |
搭乘前往轮渡的火车。 |
ROUNDABOUT_LEFT |
在环岛处左转。 |
ROUNDABOUT_RIGHT |
在环岛中右转。 |
DEPART |
初始操作。 |
NAME_CHANGE |
用于表示街道名称更改。 |
RouteLegStepTravelAdvisory
包含应通知用户的其他信息,例如路程可能的交通拥堵区域限制。
JSON 表示法 |
---|
{
"speedReadingIntervals": [
{
object ( |
字段 | |
---|---|
speedReadingIntervals[] |
注意:此字段目前未填充。 |
RouteLegStepLocalizedValues
某些属性的文本表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
字段 | |
---|---|
distance |
以文本形式表示的行程距离。 |
staticDuration |
不考虑路况因素的时长,以文本形式表示。 |
RouteLegStepTransitDetails
与 TRANSIT
路由相关的 RouteLegStep
的其他信息。
JSON 表示法 |
---|
{ "stopDetails": { object ( |
字段 | |
---|---|
stopDetails |
路段的到达和离开站点的相关信息。 |
localizedValues |
|
headsign |
根据车辆或出发站上标记的指示,指定该线路的行进方向。方向通常是终点站。 |
headway |
目前,同一车站各次发车的间隔时间会指定为预期时间。例如,当行驶秒数值为 600 时,如果您错过了一班公交,那么预计需要 10 分钟才能等到下一班。 时长以秒为单位,最多包含九个小数位,以“ |
transitLine |
此路段中使用的公交线路的相关信息。 |
stopCount |
从出发站到到达站的经停次数。此计数包括到达站,但不含出发站。例如,如果您的路线从 A 站出发,途经 B 站和 C 站,最终到达 D 站,stopCount 将会返回 3。 |
tripShortText |
显示在时间表和标牌中的文字,用于向乘客标识公交行程。文本应唯一标识服务日内的行程。例如,“538”是指在工作日 15:10 从加利福尼亚州圣何塞发车到加利福尼亚州萨克拉门托的 Amtrak 火车的 |
TransitStopDetails
有关RouteLegStep
的公交站点的详细信息。
JSON 表示法 |
---|
{ "arrivalStop": { object ( |
字段 | |
---|---|
arrivalStop |
有关路段到达站的信息。 |
arrivalTime |
相应路段的预计到达时间。 时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例: |
departureStop |
路段的出发站的相关信息。 |
departureTime |
相应路段的预计出发时间。 时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例: |
TransitStop
公交站的相关信息。
JSON 表示法 |
---|
{
"name": string,
"location": {
object ( |
字段 | |
---|---|
name |
公交站的名称。 |
location |
以纬度/经度坐标表示的车站位置。 |
TransitDetailsLocalizedValues
RouteTransitDetails
值的本地化说明。
JSON 表示法 |
---|
{ "arrivalTime": { object ( |
字段 | |
---|---|
arrivalTime |
以相应时区表示的时间(以格式化文本形式表示)。 |
departureTime |
以相应时区表示的时间(以格式化文本形式表示)。 |
LocalizedTime
时间的本地化说明。
JSON 表示法 |
---|
{
"time": {
object ( |
字段 | |
---|---|
time |
给定时区中以字符串形式指定的时间。 |
timeZone |
包含时区。该值是 IANA 时区数据库中定义的时区名称,例如“America/New_York”。 |
TransitLine
包含此路段中所用公交线路的相关信息。
JSON 表示法 |
---|
{ "agencies": [ { object ( |
字段 | |
---|---|
agencies[] |
运营此公交线路的公交公司。 |
name |
该公交线路的全名,例如“本地 8 号大道”。 |
uri |
由公交公司提供的该公交线路的 URI。 |
color |
该线路站牌上常用的颜色。以十六进制形式表示。 |
iconUri |
与此线路相关联的图标的 URI。 |
nameShort |
该公交线路的简称。此名称通常是线路编号,例如“M7”或“355”。 |
textColor |
该线路标牌上常用的文字颜色。以十六进制形式表示。 |
vehicle |
该公交线路所运营的交通工具类型。 |
TransitAgency
运营公交线路的公交公司。
JSON 表示法 |
---|
{ "name": string, "phoneNumber": string, "uri": string } |
字段 | |
---|---|
name |
此公交公司的名称。 |
phoneNumber |
公交公司根据语言区域设置的电话号码格式。 |
uri |
公交公司的 URI。 |
TransitVehicle
公交路线中使用的车辆的相关信息。
JSON 表示法 |
---|
{ "name": { object ( |
字段 | |
---|---|
name |
此车辆的名称(采用首字母大写形式)。 |
type |
使用的交通工具类型。 |
iconUri |
与此交通工具类型相关联的图标的 URI。 |
localIconUri |
与此交通工具类型相关联的图标的 URI(基于当地交通标志)。 |
TransitVehicleType
公交路线的交通工具类型。
枚举 | |
---|---|
TRANSIT_VEHICLE_TYPE_UNSPECIFIED |
未使用。 |
BUS |
公交车。 |
CABLE_CAR |
一种靠电缆运行的交通工具,通常在地面上行驶。空中缆车可以算作 GONDOLA_LIFT 类型。 |
COMMUTER_TRAIN |
通勤铁路。 |
FERRY |
轮渡。 |
FUNICULAR |
一种由缆线拉上陡坡的交通工具。索道缆车通常由两个车体组成,彼此作为对方的平衡重物。 |
GONDOLA_LIFT |
空中缆车 |
HEAVY_RAIL |
重轨。 |
HIGH_SPEED_TRAIN |
高速列车。 |
INTERCITY_BUS |
长途客车。 |
LONG_DISTANCE_TRAIN |
长途列车。 |
METRO_RAIL |
轻轨交通。 |
MONORAIL |
单轨。 |
OTHER |
所有其他车辆。 |
RAIL |
铁路。 |
SHARE_TAXI |
合乘出租车是一种可在其运行路线上随处上下乘客的公共汽车。 |
SUBWAY |
地下轻轨。 |
TRAM |
地上轻轨。 |
TROLLEYBUS |
无轨电车。 |
RouteLegTravelAdvisory
包含应在步行时告知用户的其他信息,例如可能的交通区域限制。
JSON 表示法 |
---|
{ "tollInfo": { object ( |
字段 | |
---|---|
tollInfo |
包含特定 |
speedReadingIntervals[] |
详细说明交通密度的速度读取间隔。适用于 例如:
|
RouteLegLocalizedValues
某些属性的文本表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
字段 | |
---|---|
distance |
以文本形式表示的行程距离。 |
duration |
考虑路况信息的时长,以文本形式表示。注意:如果您没有请求获取路况信息,则此值与 staticDuration 的值相同。 |
staticDuration |
不考虑路况因素的时长,以文本形式表示。 |
StepsOverview
提供关于 RouteLegStep
列表的概览信息。
JSON 表示法 |
---|
{
"multiModalSegments": [
{
object ( |
字段 | |
---|---|
multiModalSegments[] |
总结了有关 |
MultiModalSegment
提供有关 RouteLeg.steps
的不同多模态段的汇总信息。多模态片段是指具有相同 RouteTravelMode
的一个或多个连续 RouteLegStep
。如果 RouteLeg
在步骤中不包含任何多模态片段,则不会填充此字段。
JSON 表示法 |
---|
{ "navigationInstruction": { object ( |
字段 | |
---|---|
navigationInstruction |
多模态段的 NavigationInstruction。 |
travelMode |
多模式路段的出行方式。 |
stepStartIndex |
作为多模态段起点的相应 |
stepEndIndex |
多模态段末尾的相应 |
视口
纬度-经度视口,表示为两个对角线方向的 low
和 high
点。视口会被视为一个闭合区域,即包含其边界。纬度范围必须介于 -90 度(含)到 90 度(含)之间,经度范围必须在 -180 度(含)到 180 度(含)之间。各种情况包括:
如果
low
=high
,则视口将包含该单个点。如果
low.longitude
>high.longitude
,经度范围会反转(视口就会穿过 180 度经度线)。如果
low.longitude
= -180 度且high.longitude
= 180 度,则视口会包含所有经度。如果
low.longitude
= 180 度且high.longitude
= -180 度,则经度范围为空。如果
low.latitude
>high.latitude
,则纬度范围为空。
必须填充 low
和 high
,并且表示的框不能为空(如上述定义所指定)。空白视口会导致错误。
例如,以下视口会完全包围纽约市:
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON 表示法 |
---|
{ "low": { object ( |
字段 | |
---|---|
low |
必需。视口的低点。 |
high |
必需。视口的高点。 |
RouteLocalizedValues
某些属性的文本表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
字段 | |
---|---|
distance |
以文本形式表示的行程距离。 |
duration |
考虑路况信息的时长,以文本形式表示。注意:如果您未请求获取路况信息,则此值与 |
staticDuration |
不考虑路况因素的时长,以文本形式表示。 |
transitFare |
以文本形式表示的公交费用。 |
GeocodingResults
包含出发地、目的地和中间航点的
。仅为地址航点填充。GeocodedWaypoints
JSON 表示法 |
---|
{ "origin": { object ( |
字段 | |
---|---|
origin |
起点经过地理编码的航点。 |
destination |
目的地经过地理编码的航点。 |
intermediates[] |
中间地理编码路径点列表,其中每个路径点都包含一个索引字段,对应于从零开始的路标位置(按请求中指定的顺序)。 |
GeocodedWaypoint
有关用作航点的位置的详细信息。仅为地址航点填充。包含有关地理编码结果的详细信息,以便确定对地址进行地理编码。
JSON 表示法 |
---|
{
"geocoderStatus": {
object ( |
字段 | |
---|---|
geocoderStatus |
表示地理编码操作生成的状态代码。 |
type[] |
结果的类型,以零个或更多个类型标记的形式表示。支持的类型:地址类型和地址组成部分类型。 |
partialMatch |
表示地理编码器无法返回与原始请求完全匹配的结果,尽管它能够匹配所请求的地址的一部分。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。 |
placeId |
此结果的地点 ID。 |
intermediateWaypointRequestIndex |
请求中相应中间航点的索引。仅当对应航点是中间航点时填充。 |