- HTTP 请求
- 请求正文
- 响应正文
- RouteMatrixOrigin
- RouteMatrixDestination
- ExtraComputation
- RouteMatrixElementCondition
- LocalizedValues
获取起点和终点列表,并返回一个流,其中包含起点和终点的每个组合的路线信息。
注意:此方法要求您在输入中指定响应字段掩码。您可以使用网址参数 $fields
或 fields
,或使用 HTTP/gRPC 标头 X-Goog-FieldMask
提供响应字段掩码(请参阅可用的网址参数和标头)。该值是以英文逗号分隔的字段路径列表。请参阅关于如何构建字段路径的详细文档。
例如,在此方法中:
- 所有可用字段的字段掩码(用于手动检查):
X-Goog-FieldMask: *
- 路线用时、距离、元素状态、条件和元素索引(生产环境设置示例)的字段掩码:
X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration
请务必在字段掩码中添加 status
,否则所有消息都会显示为正常。Google 不建议使用通配符 (*
) 响应字段掩码,因为:
- 仅选择您需要的字段可帮助我们的服务器节省计算周期,从而以更短的延迟时间将结果返回给您。
- 仅选择生产作业中需要的字段,可确保稳定的延迟性能。我们未来可能会添加更多响应字段,这些新字段可能需要额外的计算时间。如果您选择所有字段,或者选择顶层的所有字段,则效果可能会下降,因为我们添加的所有新字段都会自动包含在响应中。
- 仅选择所需字段可以降低响应大小,从而提高网络吞吐量。
HTTP 请求
POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "origins": [ { object ( |
字段 | |
---|---|
origins[] |
必需。源站数组,用于确定响应矩阵的行。一些大小限制适用于出发地和目的地的基数:
|
destinations[] |
必需。目的地数组,用于确定响应矩阵的列。 |
travelMode |
可选。指定交通方式。 |
routingPreference |
可选。指定如何计算路由。服务器尝试使用所选路由偏好设置来计算路由。如果路由偏好设置导致错误或延迟时间过长,则系统会返回错误。只有在 |
departureTime |
可选。出发时间。如果未设置此值,则此值默认为您发出请求的时间。注意:当 时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例: |
arrivalTime |
可选。到达时间。注意:只能在 时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例: |
languageCode |
可选。BCP-47 语言代码,例如“en-US”或“sr-Latn”。如需了解详情,请参阅 Unicode 语言区域标识符。如需查看受支持语言的列表,请参阅语言支持。如果您未提供此值,系统会根据第一个出发地的位置推断显示语言。 |
regionCode |
可选。地区代码,指定为 ccTLD(“顶级域名”)双字符值。如需了解详情,请参阅国家/地区代码顶级域名。 |
extraComputations[] |
可选。可用于完成请求的额外计算的列表。注意:这些额外计算可能会在响应中返回额外字段。还必须在字段掩码中指定这些 extra 字段,以便在响应中返回。 |
trafficModel |
可选。指定计算交通时间时要使用的假设条件。此设置会影响 |
transitPreferences |
可选。指定会影响为 |
响应正文
包含针对 v2.computeRouteMatrix API 中的出发地/目的地对计算的路线信息。此 proto 可流式传输到客户端。
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 |
---|
{ "status": { object ( |
字段 | |
---|---|
status |
此元素的错误状态代码。 |
condition |
指示是否找到了路线。与状态无关。 |
distanceMeters |
路线的行程距离(以米为单位)。 |
duration |
导航路线所需的时长。如果您将 时长以秒为单位,最多包含九个小数位,以“ |
staticDuration |
不考虑路况条件时在路线上行驶的时长。 时长以秒为单位,最多包含九个小数位,以“ |
travelAdvisory |
有关路线的其他信息。例如:限制信息和收费信息 |
fallbackInfo |
在某些情况下,如果服务器无法使用此特定起点/目的地对的指定偏好设置计算路线,则可能会回退到使用其他计算模式。使用回退模式时,此字段包含有关回退响应的详细信息。否则,将取消设置此字段。 |
localizedValues |
|
originIndex |
请求中起点的索引(从零开始)。 |
destinationIndex |
请求中目的地的索引(从零开始)。 |
RouteMatrixOrigin
ComputeRouteMatrixRequest 的单个来源
JSON 表示法 |
---|
{ "waypoint": { object ( |
字段 | |
---|---|
waypoint |
必需。出发地航点 |
routeModifiers |
可选。将此作为出发地的路线的修饰符 |
RouteMatrixDestination
ComputeRouteMatrixRequest 的单个目的地
JSON 表示法 |
---|
{
"waypoint": {
object ( |
字段 | |
---|---|
waypoint |
必需。目的地航点 |
ExtraComputation
完成请求时要执行的额外计算。
枚举 | |
---|---|
EXTRA_COMPUTATION_UNSPECIFIED |
未使用。包含此值的请求将失败。 |
TOLLS |
矩阵元素的收费信息。 |
RouteMatrixElementCondition
所返回路线的使用情况。
枚举 | |
---|---|
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED |
仅在元素的 status 不适用时使用。 |
ROUTE_EXISTS |
找到了一条路线,并为元素填写了相应信息。 |
ROUTE_NOT_FOUND |
找不到路线。系统不会在该元素中填写包含路线信息的字段(例如 distanceMeters 或 duration )。 |
LocalizedValues
某些属性的文本表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
字段 | |
---|---|
distance |
以文本形式表示的行程距离。 |
duration |
以文本形式表示的时长,考虑了交通状况。注意:如果未请求路况信息,则此值与 staticDuration 的值相同。 |
staticDuration |
以文本形式表示的时长(不考虑路况信息)。 |
transitFare |
以文本形式表示的公交费用。 |