Method: computeRoutes

给定一组航点和中间航点，返回主要路线以及可选的备选路线。

注意：此方法要求您在输入中指定响应字段掩码。要提供响应字段掩码，您可以使用网址参数 $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 (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "intermediates": [
    {
      object (Waypoint)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "polylineQuality": enum (PolylineQuality),
  "polylineEncoding": enum (PolylineEncoding),
  "departureTime": string,
  "computeAlternativeRoutes": boolean,
  "routeModifiers": {
    object (RouteModifiers)
  },
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "requestedReferenceRoutes": [
    enum (ReferenceRoute)
  ],
  "extraComputations": [
    enum (ExtraComputation)
  ]
}
字段
origin

object (Waypoint)

必需。出发地航点。
destination

object (Waypoint)

必需。目标航点。
intermediates[]

object (Waypoint)

（可选）路线沿途的一组航点（不包括航站点），可在停留点经过或经过最多支持 25 个中间航点。
travelMode

enum (RouteTravelMode)

（可选）指定交通方式。
routingPreference

enum (RoutingPreference)

（可选）指定如何计算路线。服务器尝试使用所选路由偏好设置来计算路线。如果路由偏好设置导致错误或超长的延迟，则系统会返回错误。只有当 travelMode 为 DRIVE 或 TWO_WHEELER 时，您才能指定此选项，否则请求会失败。
polylineQuality

enum (PolylineQuality)

（可选）指定您对多段线质量的偏好设置。
polylineEncoding

enum (PolylineEncoding)

（可选）指定多段线的首选编码。
departureTime

string (Timestamp format)

（可选）出发时间。如果未设置此值，则此值默认为您发出请求的时间。如果您将此值设为已经发生的时间，则请求会失败。

时间戳采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式，分辨率为纳秒，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
computeAlternativeRoutes

boolean

（可选）指定是否除了计算路线外，还要计算备选路线。
routeModifiers

object (RouteModifiers)

（可选）要满足的一组条件，它们会影响路线的计算方式。
languageCode

string

（可选）BCP-47 语言代码，例如“en-US”或“sr-Latn”。如需了解详情，请参阅 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。请参阅语言支持，获取支持的语言列表。如果未提供此值，系统会根据路线请求的位置推断显示语言。
regionCode

string

（可选）地区代码，指定为 ccTLD（“顶级域名”）双字符值。有关详情，请参阅 https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains
units

enum (Units)

（可选）指定显示字段的计量单位。这包括 NavigationInstruction 中的 instruction 字段。路线、路程、路段距离和持续时间所用的测量单位不受该值的影响。如果您未提供此值，则系统会根据请求的位置推断显示单元。
requestedReferenceRoutes[]

enum (ReferenceRoute)

（可选）指定除了默认路线之外，还要作为请求一部分进行计算的参考路线。参考路线是指与默认路线不同的路线计算目标的路线。例如，FUEL_EFFICIENT 参考路线的计算会考虑将达到最节能路线的最佳参数。
extraComputations[]

enum (ExtraComputation)

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

响应正文

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

v2.computeRoutes 响应消息。

JSON 表示法 
{
  "routes": [
    {
      object (Route)
    }
  ],
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "geocodingResults": {
    object (GeocodingResults)
  }
}
字段
routes[]

object (Route)

包含一个计算路由数组（最多指定 3 个），当您指定 compute_alternatives_routes 时，如果不指定，则只包含一个路由。当此数组包含多个条目时，第一条是推荐路线。如果数组为空，就表示找不到任何路线。
fallbackInfo

object (FallbackInfo)

在某些情况下，当服务器无法使用所有输入偏好设置计算路线结果时，可能会回退到其他计算方式。使用回退模式时，此字段包含有关回退响应的详细信息。否则，该字段将处于未设置状态。
geocodingResults

object (GeocodingResults)

包含指定为地址的航点的地理编码响应信息。

多段线质量

用于指定多段线质量的一组值。

枚举
POLYLINE_QUALITY_UNSPECIFIED 未指定多段线质量偏好设置。默认为 OVERVIEW。
HIGH_QUALITY 指定优质多段线 - 该组合使用多于 OVERVIEW 个点，但响应大小会增加。如果您需要更高的精确度，请使用此值。
OVERVIEW 指定概览多段线 - 使用少量点组成。显示路线概览时使用此值。与使用 HIGH_QUALITY 选项相比，使用此选项的请求延迟时间更短。

多段线编码

指定要返回的多段线的首选类型。

枚举
POLYLINE_ENCODING_UNSPECIFIED 未指定多段线类型偏好设置。默认为 ENCODED_POLYLINE。
ENCODED_POLYLINE 用于指定使用多段线编码算法编码的多段线。
GEO_JSON_LINESTRING 使用 GeoJSON LineString 格式指定多段线

单位

一组值，用于指定显示屏中使用的计量单位。

枚举
UNITS_UNSPECIFIED 未指定测量单位。默认为根据请求推断出的计量单位。
METRIC 公制单位。
IMPERIAL 英制（英文）单位。

参考路线

ComputeRoutesRequest 中支持的参考路由。

枚举
REFERENCE_ROUTE_UNSPECIFIED 未使用。包含此值的请求会失败。
FUEL_EFFICIENT 最省油路线。标有该值的路线已确定为优化燃料消耗等参数。

额外计算

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

枚举
EXTRA_COMPUTATION_UNSPECIFIED 未使用。包含此值的请求将失败。
TOLLS 路线的收费信息。
FUEL_CONSUMPTION 路线的估算燃料消耗量。
TRAFFIC_ON_POLYLINE 路线的可感知多段线。

路线

封装路线，其中包含一系列连接了起点、终点和中间航点的相连路段。

JSON 表示法 
{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "routeToken": string
}
字段
routeLabels[]

enum (RouteLabel)

Route 的标签，可用于识别路线要与其他属性进行比较的属性。
legs[]

object (RouteLeg)

组成路线的路程集合（路标之间的路径段）。每段路程都对应于两个非 via 航点之间的行程。例如，没有任何中间航点的路线只有一段路程。一条包含 1 个非 via 中间航点的路线有两条路程。含一个 via 中间航点的路线有一段路程。路程的顺序与从 origin 到 intermediates 到 destination 的 Waypoint 的顺序一致。
distanceMeters

integer

路线的行程距离（以米为单位）。
duration

string (Duration format)

所需的路线导航时长。如果您将 routingPreference 设置为 TRAFFIC_UNAWARE，则此值与 staticDuration 相同。如果您将 routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，则系统会在计算此值时考虑到路况条件。

此时间以秒为单位，最多包含九个小数位，并以“s”结尾。示例："3.5s"。
staticDuration

string (Duration format)

不考虑路况因素而经过路线的时长。

此时间以秒为单位，最多包含九个小数位，并以“s”结尾。示例："3.5s"。
polyline

object (Polyline)

整体路线多段线。此多段线将是所有 legs 的组合多段线。
description

string

路线的说明。
warnings[]

string

显示路线时要显示的警告数组。
viewport

object (Viewport)

多段线的视口边界框。
travelAdvisory

object (RouteTravelAdvisory)

路线的其他相关信息。
routeToken

string

可传递到 NavigationSDK 的 Web 安全 base64 编码路由令牌，这允许 Navigation SDK 在导航期间重建路线，并且在重新路由的情况下，遵循调用 v2.computeRoutes 时的最初意图。客户应将此令牌视为不透明 blob。注意：Route.route_token 仅适用于将 ComputeRoutesRequest.routing_preference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL 的请求。包含 Via 航点的请求也不支持 Route.route_token。

路线标签

Route 的标签，可用于识别路线要与其他属性进行比较的属性。

枚举
ROUTE_LABEL_UNSPECIFIED 默认 - 未使用。
DEFAULT_ROUTE 为路线计算返回的默认“最佳”路线。
DEFAULT_ROUTE_ALTERNATE 默认“最佳”路线的替代方案。指定 ComputeRoutesRequest.compute_alternative_routes 后，将返回此类路由。
FUEL_EFFICIENT 最省油路线。标有该值的路线已确定针对节能参数（如油耗）进行了优化。

路线

封装非 via 航点之间的段。

JSON 表示法 
{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}
字段
distanceMeters

integer

路线路程的行程距离（以米为单位）。
duration

string (Duration format)

浏览腿部所需的时长。如果 route_preference 设置为 TRAFFIC_UNAWARE，则此值与 staticDuration 相同。如果 route_preference 为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，则计算该值时会考虑路况条件。

此时间以秒为单位，最多包含九个小数位，并以“s”结尾。示例："3.5s"。
staticDuration

string (Duration format)

路程的持续时间，计算时不考虑交通状况。

此时间以秒为单位，最多包含九个小数位，并以“s”结尾。示例："3.5s"。
polyline

object (Polyline)

此路程的整体多段线。这包括每个 step 的多段线。
startLocation

object (Location)

此路程的起始位置。它可能与提供的 origin 不同。例如，如果提供的 origin 不靠近道路，则这是道路上的一个点。
endLocation

object (Location)

此路程的结束位置。它可能与提供的 destination 不同。例如，如果提供的 destination 不靠近道路，则这是道路上的一个点。
steps[]

object (RouteLegStep)

表示该路程内路段的一系列路段。每个步骤代表一个导航指令。
travelAdvisory

object (RouteLegTravelAdvisory)

封装应通知用户的其他信息，例如路线路段上可能发生的路况区域限制等。

多段线

封装编码多段线。

JSON 表示法 
{

  // Union field polyline_type can be only one of the following:
  "encodedPolyline": string,
  "geoJsonLinestring": {
    object
  }
  // End of list of possible types for union field polyline_type.
}
字段
联合字段 polyline_type。封装多段线的类型。默认为 encoded_polyline。polyline_type 只能是下列其中一项：
encodedPolyline

string

使用多段线编码算法进行多段线的字符串编码
geoJsonLinestring

object (Struct format)

使用 GeoJSON LineString 格式指定多段线

RouteLegStep

封装 RouteLeg 的细分。每个步骤对应一个导航指令。路线路段由各个路段组成。

JSON 表示法 
{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  },
  "travelAdvisory": {
    object (RouteLegStepTravelAdvisory)
  }
}
字段
distanceMeters

integer

此路段的行驶距离（以米为单位）。在某些情况下，此字段可能没有值。
staticDuration

string (Duration format)

不考虑路况信息情况下该路段的行程时长。在某些情况下，此字段可能没有值。

此时间以秒为单位，最多包含九个小数位，并以“s”结尾。示例："3.5s"。
polyline

object (Polyline)

与此步骤关联的多段线。
startLocation

object (Location)

此步骤的起始位置。
endLocation

object (Location)

此步骤的结束位置。
navigationInstruction

object (NavigationInstruction)

导航说明。
travelAdvisory

object (RouteLegStepTravelAdvisory)

封装应告知用户的其他信息，例如针对路程步骤可能的车流量限制。

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 在环岛处右转。

RouteLegStepTravelAdvisory（咨询）

封装应告知用户的其他信息，例如针对路程步骤可能的车流量限制。

JSON 表示法 
{
  "speedReadingIntervals": [
    {
      object (SpeedReadingInterval)
    }
  ]
}
字段
speedReadingIntervals[]

object (SpeedReadingInterval)

注意：此字段目前没有填充。

航线旅行咨询

封装应通知用户的其他信息，例如路线路段上可能发生的路况区域限制等。

JSON 表示法 
{
  "tollInfo": {
    object (TollInfo)
  },
  "speedReadingIntervals": [
    {
      object (SpeedReadingInterval)
    }
  ]
}
字段
tollInfo

object (TollInfo)

封装特定 RouteLeg 的收费信息。仅当我们预计 RouteLeg 上有收费站时，才会填充此字段。如果已设置此字段，但估计值子字段未填充，则我们预计该道路包含收费路段，但不知道估算价格。如果此字段不存在，则 RouteLeg 不收取任何费用。
speedReadingIntervals[]

object (SpeedReadingInterval)

详细说明流量密度的速度读数间隔。适用于 TRAFFIC_AWARE 和 TRAFFIC_AWARE_OPTIMAL 路由偏好设置。这些间隔覆盖了 RouteLg 的整个多段线而不重叠。指定间隔的起点与上一间隔的终点相同。

例如：

polyline: A ---- B ---- C ---- D ---- E ---- F ---- G
speedReadingIntervals: [A,C), [C,D), [D,G).

视口

纬度/经度视口，以对角线对角的 low 和 high 点表示。视口被视为封闭区域，即包含边界。纬度范围必须介于 -90 度（含）和 -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": { "纬度": 40.477398, "经度": -74.259087 }, "high": { "纬度": 40.91618, "经度": -73.70018 } }

JSON 表示法 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
字段
low

object (LatLng)

必需。视口的低点。
high

object (LatLng)

必需。视口的高点。

地理编码结果

包含出发地、目的地和中间航点的 GeocodedWaypoints。仅针对地址航点填充。

JSON 表示法 
{
  "origin": {
    object (GeocodedWaypoint)
  },
  "destination": {
    object (GeocodedWaypoint)
  },
  "intermediates": [
    {
      object (GeocodedWaypoint)
    }
  ]
}
字段
origin

object (GeocodedWaypoint)

经过地理编码的航点。
destination

object (GeocodedWaypoint)

目的地经过地理编码的航点。
intermediates[]

object (GeocodedWaypoint)

中间经过地理编码的路标列表，其中每个路标均包含一个索引字段，其对应于从点开始的零位置（按照请求中指定的顺序）。

经过地理编码的 Waypoint

有关用作航点的地点的详细信息。仅针对地址航点填充。包含有关地理编码结果的详情，用于确定地理编码地址。

JSON 表示法 
{
  "geocoderStatus": {
    object (Status)
  },
  "type": [
    string
  ],
  "partialMatch": boolean,
  "placeId": string,
  "intermediateWaypointRequestIndex": integer
}
字段
geocoderStatus

object (Status)

指明通过地理编码操作生成的状态代码。
type[]

string

结果的类型，采用零个或多个类型标记的形式。支持的类型：https://developers.google.com/maps/documentation/Geocoding/requests-Geocoding#Types
partialMatch

boolean

表示地理编码器无法返回与原始请求完全匹配的结果，尽管它能够匹配所请求地址的一部分。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。
placeId

string

此结果的地点 ID。
intermediateWaypointRequestIndex

integer

请求中相应中间航点的索引。仅当相应的路标是中间路标时填充。