Route (beta)

Route 类

google.maps.routes.Route 类

包含路线，该路线由一系列相连的路段组成，这些路段连接起点、终点和中间航点。

通过调用 const {Route} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
computeRoutes
computeRoutes(request)
参数： 
返回值：  Promise<{
  routes:Array<Route> optional,
  fallbackInfo:FallbackInfo optional,
  geocodingResults:GeocodingResults optional
}>
根据一组终点和中间航点返回主要路线以及可选的备选路线。

注意：此方法要求您通过设置 ComputeRoutesRequest.fields 属性在请求中指定响应字段掩码。该值是字段路径的列表。

例如：
  • 所有可用字段的字段掩码：fields: ['*']
  • 路线级时长、距离和路径的字段掩码：fields: ['durationMillis', 'distanceMeters', 'path']

不建议使用通配符响应字段掩码 fields: ['*']，因为：
  • 仅选择您需要的字段有助于我们的服务器节省计算周期，从而使我们能够以更低的延迟时间向您返回结果。
  • 仅选择生产作业中需要的字段可确保稳定的延迟时间性能。我们未来可能会添加更多响应字段，而这些新字段可能需要额外的计算时间。如果您选择所有字段，或者选择顶级的所有字段，则可能会遇到性能下降的问题，因为我们添加的任何新字段都会自动包含在响应中。
  • 仅选择所需的字段可减小响应大小，从而加快网络加载速度。
description
类型：  string optional
路线的说明。
distanceMeters
类型：  number optional
相应路线的行驶距离（以米为单位）。
durationMillis
类型：  number optional
导航路线所需的时间（以毫秒为单位）。如果您将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_UNAWARE，则此值与 Route.staticDurationMillis 相同。如果您将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，则系统会根据路况计算此值。

注意：如果时长超过 2^53 毫秒，则此值为 Number.POSITIVE_INFINITY。
legs
类型：  Array<RouteLeg> optional
构成路线的若干路段（航点之间的路径段）。每段行程都对应于两个非 via 航点之间的旅程。

例如：
  • 没有中间航点的路线只有一段路程。
  • 包含一个非 via 中间航点的路线有两段路程。
  • 包含一个 via 中间航点的路线有一段路程。
路段的顺序与途经点的顺序一致，即从 origin 到 intermediates 再到 destination。
localizedValues
类型：  RouteLocalizedValues optional
Route 的属性的文本表示形式。
optimizedIntermediateWaypointIndices
类型：  Array<number> optional
如果您将 ComputeRoutesRequest.optimizeWaypointOrder 设置为 true，此字段将包含优化后的中途经停点顺序。否则，此字段为空。索引从 0 开始，表示输入中提供的第一个中间途经点。

例如，如果您输入：
  • 来源：LA
  • 中间航点：达拉斯、班戈、凤凰城
  • 目的地：纽约
，而优化后的中间航点顺序为 Phoenix、Dallas、Bangor，则此字段将为 [2, 0, 1]。
path
类型：  Array<LatLngAltitude> optional
路线的 LatLngAltitude 列表，可用于绘制路线多段线。可以通过设置 ComputeRoutesRequest.polylineQuality 来控制路径的粒度。
polylineDetails
类型：  PolylineDetails optional
包含有关路径沿途的详细信息。
routeLabels
类型：  Array<RouteLabel> optional
有助于识别路线特定属性或与其他路线进行比较的标签。
routeToken
类型：  string optional
一个不透明的令牌，可传递给 Navigation SDK 以在导航期间重建路线，并在重新规划路线时遵循创建路线时的原始意图。将此令牌视为不透明 blob。请勿跨请求比较其值，因为即使服务返回完全相同的路线，其值也可能会发生变化。

注意：routeToken 仅适用于将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL 的请求。不支持包含 via 航点的请求。
speedPaths
类型：  Array<SpeedPath> optional
路线路径的各个部分及其对应的速度读数。若要填充此字段，必须将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，并且 ComputeRoutesRequest.extraComputations 必须包含 TRAFFIC_ON_POLYLINE。
staticDurationMillis
类型：  number optional
在不考虑路况的情况下，沿路线行驶所需的时间。

注意：如果时长超过 2^53 毫秒，则此值为 Number.POSITIVE_INFINITY。
travelAdvisory
类型：  RouteTravelAdvisory optional
有关路线的其他信息。
viewport
类型：  LatLngBounds optional
路线的视口边界框。
warnings
类型：  Array<string> optional
在显示路线时要显示的一系列警告。
createPolylines
createPolylines([options])
参数： 
返回值：  Array<Polyline>
根据可用数据为路线创建折线。

多模态多段线：
  • 要求：
  • 为每个多模式路线段创建一条多段线。折线会根据路段出行方式和公交线路数据（如有）设置样式。您可以传入选项，以根据出行方式和公交线路更改折线样式。

流量多段线：
总体折线：
  • 要求：
  • 为整个路线创建一条应用了默认样式的多段线。可以传入选项，以根据路线出行方式更改多段线样式。如需进一步自定义，请使用 Route.path 或 RouteLeg.path 直接创建多段线。
createWaypointAdvancedMarkers
createWaypointAdvancedMarkers([options])
参数： 
返回值：  Promise<Array<AdvancedMarkerElement>>
为每个途经点创建标记，并为路线添加“A”“B”“C”等标签。标记已应用默认样式。您可以传入选项，以根据标记指数或相应 RouteLeg 的属性来更改标记样式。如果路线没有路段，则 WaypointMarkerDetails.leg 参数将为未定义。

必须在 ComputeRoutesRequest.fields 中请求 "legs" 字段，才能包含中间途经点。
toJSON
toJSON()
参数：无
返回值：  Object
转换为对象。

ComputeRoutesRequest 接口

google.maps.routes.ComputeRoutesRequest 接口

路线请求。
destination
相应路线的目的地。以字符串形式传递的值可以是地址、plus code 或 Place 资源名称。计算路线时不会考虑海拔高度值。
fields
类型：  Iterable<string>
要提取的字段的集合。为所有字段指定 ["*"]。
origin
路线的起点。以字符串形式传递的值可以是地址、plus code 或 Place 资源名称。计算路线时不会考虑海拔高度值。
arrivalTime optional
类型：  Date optional
到达时间。

注意：只有当 ComputeRoutesRequest.travelMode 设置为 TRANSIT 时才能设置此项。您可以指定 ComputeRoutesRequest.departureTime 或 ComputeRoutesRequest.arrivalTime，但不能同时指定这两者。公交行程最多可查询过去 7 天或未来 100 天的行程。
computeAlternativeRoutes optional
类型：  boolean optional
指定是否在计算路线的同时计算备选路线。对于包含中间途经点的请求，系统不会返回替代路线。
departureTime optional
类型：  Date optional
出发时间。如果您未设置此值，则此值默认为您发出请求的时间。

注意：只有当 ComputeRoutesRequest.travelMode 设置为 TRANSIT 时，您才能指定过去的时间。公交行程最多可查询过去 7 天或未来 100 天的行程。
extraComputations optional
可用于完成请求的额外计算的列表。

注意：这些额外的计算可能会在响应中返回额外的字段。这些额外的字段也必须在 ComputeRoutesRequest.fields 中指定，才能在响应中返回。
intermediates optional
类型：  Iterable<Waypoint> optional
路线中的一组途经点（不包括终点），用于停靠或途经。最多支持 25 个中间航点。
language optional
类型：  string optional
BCP-47 语言代码，例如“en-US”或“sr-Latn”。如需了解详情，请参阅 Unicode 语言区域标识符。如需查看支持的语言列表，请参阅语言支持。如果您未提供此值，系统会根据您的 Google Maps JavaScript API 本地化设置推断语言。否则，系统会根据来源的位置推断语言。
optimizeWaypointOrder optional
类型：  boolean optional
如果设置为 true，服务会尝试通过重新排序指定的中途经停点来最大限度地降低路线的总费用。如果任何中间航点是途经航点，请求都会失败。使用响应中的 Route.optimizedIntermediateWaypointIndices 查找新的排序。如果未在 ComputeRoutesRequest.fields 中请求 "optimizedIntermediateWaypointIndices"，则请求失败。如果设置为 false，则响应中的 Route.optimizedIntermediateWaypointIndices 将为空。
polylineQuality optional
类型：  PolylineQuality optional
指定对折线质量的偏好设置。
region optional
类型：  string optional
地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。如需了解详情，请参阅国家/地区代码顶级网域。如果您未提供此值，系统会根据您的 Google Maps JavaScript API 本地化设置推断区域。否则，系统会根据来源的位置推断区域。
requestedReferenceRoutes optional
类型：  Iterable<ReferenceRoute> optional
指定除了默认路线之外，还要计算哪些参考路线作为请求的一部分。参考路线是指路线计算目标与默认路线不同的路线。例如，FUEL_EFFICIENT参考路线计算会考虑各种参数，以生成最佳的省油路线。使用此功能时，请在生成的路线中查找 Route.routeLabels。
routeModifiers optional
类型：  RouteModifiers optional
一组需要满足的条件，这些条件会影响路线的计算方式。例如，您可以指定要避开的道路，如收费公路或高速公路。
routingPreference optional
类型：  RoutingPreference optional
指定如何计算路线。服务器会尝试使用所选的路由偏好设置来计算路由。如果路由偏好设置导致错误或延迟时间过长，则返回错误。只有当 ComputeRoutesRequest.travelMode 为 DRIVING 或 TWO_WHEELER 时，您才能指定此选项，否则请求会失败。
trafficModel optional
类型：  TrafficModel optional
指定计算交通中的时间时要使用的假设。此设置会影响 Route.durationMillis 和 RouteLeg.durationMillis 的值，这两个值包含根据历史平均数据预测的交通时间。ComputeRoutesRequest.trafficModel 仅适用于将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_AWARE_OPTIMAL 且将 ComputeRoutesRequest.travelMode 设置为 DRIVING 的请求。默认值为 BEST_GUESS。
transitPreference optional
类型：  TransitPreference optional
指定影响为 TRANSIT 路线返回的路线的偏好设置。

注意：只有当 ComputeRoutesRequest.travelMode 设置为 TRANSIT 时才能指定此参数。
travelMode optional
类型：  TravelMode optional
指定交通方式。
units optional
类型：  UnitSystem optional
指定显示字段（例如导航说明）的度量单位。此值不会影响用于路线、路段、步数距离和时长的计量单位。如果您未提供此值，则系统会根据原点的位置推断显示单位。

ComputeRoutesExtraComputation 常量

google.maps.routes.ComputeRoutesExtraComputation 常量

要针对 Route.computeRoutes 请求执行的额外计算。

通过调用 const {ComputeRoutesExtraComputation} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
FLYOVER_INFO_ON_POLYLINE 相应路线的 Flyover 信息。必须在 ComputeRoutesRequest.fields 中指定 "polylineDetails" 字段才能返回此信息。目前，此数据仅会针对印度境内的某些大都市区进行填充。此功能目前处于实验阶段，SKU/费用可能会发生变化。
FUEL_CONSUMPTION 相应路线的估计燃料消耗量。
HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 以格式化 HTML 文本字符串形式呈现的导航说明。此内容应按原样读取，仅用于显示。请勿以程序化方式解析此内容。
NARROW_ROAD_INFO_ON_POLYLINE 相应路线的狭窄道路信息。必须在 ComputeRoutesRequest.fields 中指定 "polylineDetails" 字段才能返回此信息。目前，此数据仅会针对印度境内的某些大都市区进行填充。此功能目前处于实验阶段，SKU/费用可能会发生变化。
TOLLS 相应路线的过路费信息。
TRAFFIC_ON_POLYLINE 路线的可感知路况的多段线。

DirectionalLocationLiteral 接口

google.maps.routes.DirectionalLocationLiteral 接口

为了方便起见，系统接受对象字面量来代替 DirectionalLocation 实例。当 Maps JS API 遇到这些值时，会将它们转换为 DirectionalLocation。

此接口扩展了 LatLngAltitudeLiteral。

heading optional
类型：  number optional
与交通流量方向相关的罗盘方向。航向值可以是 0 到 360 之间的数字，其中 0 表示正北方向，90 表示正东方向，依此类推。您只能将此字段用于 DRIVING 和 TWO_WHEELER ComputeRoutesRequest.travelMode。
继承： altitude、 lat、 lng

DirectionalLocation 类

google.maps.routes.DirectionalLocation 类

封装地理点和可选的航向。

此类扩展了 LatLngAltitude。

此类实现了 DirectionalLocationLiteral。

通过调用 const {DirectionalLocation} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
继承自： LatLngAltitude
heading
类型：  number optional
与交通流量方向相关的罗盘方向。航向值可以是 0 到 360 之间的数字，其中 0 表示正北方向，90 表示正东方向，依此类推。您只能将此字段用于 DRIVING 和 TWO_WHEELER ComputeRoutesRequest.travelMode。
继承： altitude、 lat、 lng
toJSON
toJSON()
参数：无
返回值：  DirectionalLocationLiteral
转换为对象。
继承自： equals

FallbackInfo 类

google.maps.routes.FallbackInfo 类

与 Route.computeRoutes 响应中使用回退结果的方式和原因相关的信息。如果设置了此字段，则表示服务器使用了与您的首选模式不同的路由模式作为回退。

通过调用 const {FallbackInfo} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
reason
类型：  FallbackReason optional
之所以使用回退响应而非原始响应的原因。仅当触发回退模式并返回回退响应时，才会填充此字段。
routingMode
类型：  FallbackRoutingMode optional
用于响应的路由模式。如果触发了回退，则模式可能与原始客户端请求中设置的路由偏好不同。

FallbackReason 常量

google.maps.routes.FallbackReason 常量

在 Route.computeRoutes 响应中返回回退响应的原因。

通过调用 const {FallbackReason} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
LATENCY_EXCEEDED 我们无法及时完成使用首选路线模式进行的计算，但能够返回使用替代模式计算出的结果。
SERVER_ERROR 在以首选路线模式计算路线时，系统发生了服务器错误，但我们能够返回以替代模式计算的结果。

FallbackRoutingMode 常量

google.maps.routes.FallbackRoutingMode 常量

在 Route.computeRoutes 响应中返回后备响应时使用的实际路由模式。

通过调用 const {FallbackRoutingMode} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
TRAFFIC_AWARE 表示已使用 TRAFFIC_AWARE RoutingPreference 计算响应。
TRAFFIC_UNAWARE 表示已使用 TRAFFIC_UNAWARE RoutingPreference 计算响应。

GeocodedWaypoint 类

google.maps.routes.GeocodedWaypoint 类

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

通过调用 const {GeocodedWaypoint} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
geocoderStatus
类型：  RPCStatus optional
表示地理编码操作生成的状态代码。
intermediateWaypointRequestIndex
类型：  number optional
相应中间途经点在请求中的索引。仅当相应途经点为中间途经点时填充。
partialMatch
类型：  boolean
表示地理编码器无法返回与原始请求完全匹配的结果，尽管它能够匹配所请求地址的一部分内容。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。
placeId
类型：  string
相应结果的地点 ID。
types
类型：  Array<string>
结果的类型，以零个或多个类型标记的形式表示。如需查看支持的类型，请参阅 https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types。
toJSON
toJSON()
参数：无
返回值：  Object
转换为对象。

GeocodingResults 类

google.maps.routes.GeocodingResults 类

包含出发地、目的地和中间途经点的 GeocodedWaypoint。仅针对地址途经点填充。

通过调用 const {GeocodingResults} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
destination
类型：  GeocodedWaypoint optional
目的地的地理编码航点。
intermediates
类型：  Array<GeocodedWaypoint> optional
中间地理编码航点的列表，每个航点都包含一个索引字段，该字段对应于航点在请求中指定的顺序中的从零开始的位置。
origin
类型：  GeocodedWaypoint optional
出发地的地理编码航点。
toJSON
toJSON()
参数：无
返回值：  Object
转换为对象。

MultiModalSegment 类

google.maps.routes.MultiModalSegment 类

提供路线的 RouteLeg.steps 多种模式路段的摘要信息。多模态片段是指具有相同 TravelMode 的一个或多个连续 RouteLegStep。

通过调用 const {MultiModalSegment} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
instructions
类型：  string optional
有关如何浏览此多模态片段的说明。
maneuver
类型：  string optional
在此步骤中要执行的导航操作。如需查看可能值的列表，请参阅机动。
stepEndIndex
类型：  number
多模态片段末尾对应的 RouteLegStep 索引。
stepStartIndex
类型：  number
多模态片段的起始位置对应的 RouteLegStep 索引。
travelMode
类型：  TravelMode optional
相应多模态路段所用的出行方式。
toJSON
toJSON()
参数：无
返回值：  Object
转换为对象。

PolylineDetailInfo 类

google.maps.routes.PolylineDetailInfo 类

封装了多段线一段路线上道路要素的相关信息。

通过调用 const {PolylineDetailInfo} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
endIndex
类型：  number optional
相应道路要素在多段线中的结束索引。
presence
类型：  RoadFeatureState optional
表示多段线上是否存在道路要素。
startIndex
类型：  number optional
相应道路要素在多段线中的起始索引。
toJSON
toJSON()
参数：无
返回值：  Object
转换为对象。

PolylineDetails 类

google.maps.routes.PolylineDetails 类

与多段线的指定索引或连续段对应的详细信息。对于具有点 P_0、P_1、...、P_N（从零开始的索引）的多段线，PolylineDetails 描述了给定区间内的道路特征。

通过调用 const {PolylineDetails} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
flyoverInfo
沿多段线的飞掠详情。
narrowRoadInfo
多段线沿途的狭窄道路详细信息。
toJSON
toJSON()
参数：无
返回值：  Object
转换为对象。

PolylineQuality 常量

google.maps.routes.PolylineQuality 常量

指定折线的质量。

通过调用 const {PolylineQuality} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
HIGH_QUALITY 指定使用比 OVERVIEW 更多的点组成的高质量折线，但会增加响应大小。如果需要更高的精度，请使用此值。
OVERVIEW 指定使用少量点组成的概览折线。与 HIGH_QUALITY 相比，使用此选项的请求延迟时间更短。在显示路线概览时使用此值。

ReferenceRoute 常量

google.maps.routes.ReferenceRoute 常量

ComputeRoutesRequest 上支持的参考路线。

通过调用 const {ReferenceRoute} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
FUEL_EFFICIENT 省油路线。
SHORTER_DISTANCE 行程距离较短的路线。

RoadFeatureState 常量

google.maps.routes.RoadFeatureState 常量

封装多段线一段上的道路功能状态。

通过调用 const {RoadFeatureState} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
DOES_NOT_EXIST 道路要素不存在。
EXISTS 道路要素存在。

RouteLabel 常量

google.maps.routes.RouteLabel 常量

有助于识别要与其他房源进行比较的特定房源的路线标签。

通过调用 const {RouteLabel} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
DEFAULT_ROUTE 为路线计算返回的默认“最佳”路线。
DEFAULT_ROUTE_ALTERNATE 默认“最佳”路线的替代方案。指定 ComputeRoutesRequest.computeAlternativeRoutes 时，系统将返回此类路线。
FUEL_EFFICIENT 省油路线。标记有此值的路线被确定为针对燃油消耗等环保参数进行了优化。
SHORTER_DISTANCE 行驶距离较短的路线。这是一项实验性功能。

RouteLeg 类

google.maps.routes.RouteLeg 类

包含非 via 航点之间的路段。

通过调用 const {RouteLeg} = await google.maps.importLibrary("routes") 进行访问。
请参阅 Maps JavaScript API 中的库。
distanceMeters
类型：  number
相应路线段的行驶距离（以米为单位）。
durationMillis
类型：  number optional
导航路线段所需的时间（以毫秒为单位）。如果您将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_UNAWARE，则此值与 staticDurationMillis 相同。如果您将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，则系统会根据路况计算此值。

注意：如果时长超过 2^53 毫秒，则此值为 Number.POSITIVE_INFINITY。
endLocation
类型：  DirectionalLocation optional
相应路段的终点位置。此位置可能与 ComputeRoutesRequest.destination 不同。例如，当 ComputeRoutesRequest.destination 不在道路附近时，这是道路上的一个点。
localizedValues
类型：  RouteLegLocalizedValues optional
RouteLeg 的属性的文本表示形式。
path
类型：  Array<LatLngAltitude>
路线段的 LatLngAltitude 列表，可用于绘制路线段多段线。可以通过设置 ComputeRoutesRequest.polylineQuality 来控制路径的粒度。
speedPaths
类型：  Array<SpeedPath>
路段路径的各个部分及其对应的速度读数的分组。若要填充此字段，必须将 ComputeRoutesRequest.routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，并且 ComputeRoutesRequest.extraComputations 必须包含 TRAFFIC_ON_POLYLINE。
startLocation
类型：  DirectionalLocation optional
相应路段的起点。此位置可能与 ComputeRoutesRequest.origin 不同。例如，当 ComputeRoutesRequest.origin 不在道路附近时，这是道路上的一个点。