Method: computeRouteMatrix

获取出发地和目的地列表,并返回包含每种出发地和目的地组合的路线信息的数据流。

注意:此方法要求您在输入中指定响应字段掩码。您可以通过以下两种方式提供响应字段掩码:使用网址参数 $fieldsfields,或者使用 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 (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
字段
origins[]

object (RouteMatrixOrigin)

必需。原点数组,用于确定响应矩阵的行。出发地和目的地的基数有以下几种大小限制:

  • 出发地数量与指定为 placeIdaddress 的目的地数量之和不得超过 50。
  • 在任何情况下,出发地数量 × 目的地数量的乘积都不得超过 625。
  • 如果路由 Preference 设置为 TRAFFIC_AWARE_OPTIMAL,则出发地数量 × 目的地数量的乘积不得超过 100。
  • 如果 travelMode 设置为 TRANSIT,则出发地数量 × 目的地数量的乘积不得超过 100。
destinations[]

object (RouteMatrixDestination)

必需。目的地数组,用于确定响应矩阵的列。

travelMode

enum (RouteTravelMode)

可选。指定交通方式。

routingPreference

enum (RoutingPreference)

可选。指定如何计算路线。服务器会尝试使用所选的路由偏好设置来计算路由。如果路由偏好设置导致错误或延迟时间过长,则返回错误。只有在 travelModeDRIVETWO_WHEELER 时才能指定此选项,否则请求会失败。

departureTime

string (Timestamp format)

可选。出发时间。如果未设置此值,则此值默认为您发出请求的时间。注意:当 RouteTravelMode 设置为 TRANSIT 时,您只能指定过去的 departureTime

时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

arrivalTime

string (Timestamp format)

可选。到达时间。注意:只有在 RouteTravelMode 设置为 TRANSIT 时才能设置。您可以指定 departureTimearrivalTime,但不能同时指定这两者。

时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

languageCode

string

可选。BCP-47 语言代码,例如“en-US”或“sr-Latn”。如需了解详情,请参阅 Unicode 语言区域标识符。如需查看受支持语言的列表,请参阅语言支持。如果您未提供此值,系统会根据第一个源的位置推断显示语言。

regionCode

string

可选。地区代码,指定为 ccTLD(“顶级域名”)双字符值。如需了解详情,请参阅国家/地区代码顶级域名

units

enum (Units)

可选。指定显示字段的测量单位。

extraComputations[]

enum (ExtraComputation)

可选。可用于完成请求的额外计算的列表。注意:这些额外的计算可能会在响应中返回额外字段。此外,您还必须在要在响应中返回的字段掩码中指定这些额外字段。

trafficModel

enum (TrafficModel)

可选。指定计算交通时间时要使用的假设条件。此设置会影响 RouteMatrixElement 中的时长字段中返回的值,其中包含根据历史平均值预测的交通时间。RoutingPreferenceTRAFFIC_AWARE_OPTIMALRouteTravelModeDRIVE。如果请求了流量但未指定 TrafficModel,则默认值为 BEST_GUESS

transitPreferences

object (TransitPreferences)

可选。指定影响为 TRANSIT 路由返回的路由的偏好设置。注意:只有在 RouteTravelMode 设置为 TRANSIT 时,您才能指定 transitPreferences

响应正文

包含针对 v2.computeRouteMatrix API 中针对出发地/目的地对计算的路线信息。此 proto 可以流式传输到客户端。

如果成功,响应正文将包含结构如下的数据:

JSON 表示法
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
字段
status

object (Status)

此元素的错误状态代码。

condition

enum (RouteMatrixElementCondition)

指示是否找到该路由。与状态无关。

distanceMeters

integer

路线的行程距离(以米为单位)。

duration

string (Duration format)

导航路线所需的时长。如果您将 routingPreference 设置为 TRAFFIC_UNAWARE,则此值与 staticDuration 相同。如果您将 routingPreference 设置为 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL,则系统在计算此值时会考虑到路况信息。

该时长以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

staticDuration

string (Duration format)

在不考虑路况信息的情况下通过路线的时长。

该时长以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

travelAdvisory

object (RouteTravelAdvisory)

有关该路线的其他信息。例如:限制信息和收费信息

fallbackInfo

object (FallbackInfo)

在某些情况下,如果服务器无法根据这个特定起点/终点对的指定偏好来计算路线,则可能会回退到使用其他计算模式。使用回退模式时,此字段包含有关回退响应的详细信息。否则,此字段将处于未设置状态。

localizedValues

object (LocalizedValues)

RouteMatrixElement 属性的文本表示形式。

originIndex

integer

请求中来源的索引(从零开始)。

destinationIndex

integer

请求中目的地的索引(从零开始)。

RouteMatrixOrigin

ComputeRouteMatrixRequest 的单个源

JSON 表示法
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
字段
waypoint

object (Waypoint)

必需。出发地航点

routeModifiers

object (RouteModifiers)

可选。以此为起点的每个路线的修饰符

RouteMatrixDestination

ComputeRouteMatrixRequest 的单个目标

JSON 表示法
{
  "waypoint": {
    object (Waypoint)
  }
}
字段
waypoint

object (Waypoint)

必需。目的地航点

ExtraComputation

完成请求时要执行的额外计算。

枚举
EXTRA_COMPUTATION_UNSPECIFIED 未使用。包含此值的请求将失败。
TOLLS 矩阵元素的收费信息。

RouteMatrixElementCondition

所返回路线的条件。

枚举
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED 仅在元素的 status 不适用时使用。
ROUTE_EXISTS 已找到路线,并为元素填写了相应的信息。
ROUTE_NOT_FOUND 找不到路线。该元素中不会填写包含路线信息(如 distanceMetersduration)的字段。

LocalizedValues

某些属性的文本表示。

JSON 表示法
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
字段
distance

object (LocalizedText)

以文本形式表示的行程距离。

duration

object (LocalizedText)

在考虑路况信息的情况下,以文本形式表示的时长。注意 :如果未请求路况信息,则此值与 staticDuration 相同。

staticDuration

object (LocalizedText)

以文本形式表示的时长,不考虑路况信息。

transitFare

object (LocalizedText)

以文本形式表示的公交票价。