通过 Directions API（旧版）获取路线

借助 Directions API（旧版），您可以：

• 搜索多种交通方式（包括公交、驾车、步行或骑行）的路线。
• 通过一系列路径点返回多段式路线。
• 将出发地、目的地和航点指定为文本字符串（即“伊利诺伊州芝加哥市”或“澳大利亚北领地达尔文市”）、地点 ID 或纬度/经度坐标。

该 API 在计算路线时会返回最高效的路线。行程时间是主要因素且进行了优化，但在确定哪条路线最高效时，该 API 也可以将距离、转弯次数及许多其他因素考虑在内。

准备工作

在开始使用 Directions API（旧版）之前，请确保您的项目已关联结算账号并且启用了 Directions API（旧版）。如需了解详情，请参阅在 Cloud 控制台中进行设置。

构建 Directions API（旧版）请求

Directions API（旧版）请求采用以下形式：

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

其中 outputFormat 可以是以下任一值：

• json（推荐）表示以 JavaScript 对象表示法 (JSON) 格式输出
• xml 表示输出为 XML

注意：网址必须经过正确编码才有效，并且对于所有网络服务，网址最多可包含 16384 个字符。在构建网址时，请注意此限制。

依照网址的标准，所有参数都使用“与”符号 (&) 分隔。所有保留字符（例如加号“+”）都必须经过网址编码。下面枚举了这些参数及其可能的值。

必需参数

目标账号

您要计算路线的目的地的地点 ID、地址或文本纬度/经度值。目的地参数的选项与来源参数的选项相同。

源

您要计算路线的出发地地点 ID、地址或文本纬度/经度值。

• 地点 ID 必须带有 place_id: 前缀。您可以从 Geocoding API 和 Places API（包括地点自动补全）检索地点 ID。如需查看使用来自地点自动补全服务的地点 ID 的示例，请参阅地点自动补全和路线。如需详细了解地点 ID，请参阅地点 ID 概览。

  origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  

• 如果您传递地址，路线服务会对字符串进行地理编码，并将其转换为纬度/经度坐标，以计算路线。此坐标可能与 Geocoding API 返回的坐标不同，例如，它可能是建筑物入口，而不是建筑物中心。

  origin=24+Sussex+Drive+Ottawa+ON
  

  最好使用地点 ID，而不是地址或纬度/经度坐标。使用坐标始终会导致点被吸附到最靠近这些坐标的道路上，而该道路可能不是房源的入口，甚至可能不是能够快速或安全到达目的地的道路。

• 如果您传递坐标，该点将贴靠到最近的道路。 最好传递地点 ID。如果您确实传递了坐标，请确保纬度值和经度值之间没有空格。

  origin=41.43206,-81.38992
  

• Plus Code 必须采用全局代码或混合代码格式。 按如下格式设置 Plus Codes（加号经网址转义为 %2B，空格经网址转义为 %20）。

  • 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码（849VCWC8+R9 为 849VCWC8%2BR9）。
  • 混合代码是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9 Mountain View, CA, USA 为 CWC8%2BR9%20Mountain%20View%20CA%20USA）。

可选参数

替代方案

如果设置为 true，则指定路线服务可以在响应中提供多条备选路线。请注意，提供备选路线可能会增加服务器的响应时间。此字段仅适用于没有中间航点的请求。如需了解详情，请参阅航点指南。

arrival_time

指定公共交通路线的首选到达时间，以自世界协调时间 (UTC) 1970 年 1 月 1 日午夜起经过的秒数表示。您可以指定 departure_time 或 arrival_time，但不能同时指定这两者。 请注意，arrival_time 必须指定为整数。

避免

表示计算出的路线应避开指定的地图项。此参数支持以下实参：

• tolls 表示计算出的路线应避开收费路段/桥梁。
• highways 表示计算出的路线应避开高速公路。
• ferries 表示计算出的路线应避开轮渡。
• indoor 表示计算出的路线应避免在步行和公共交通路线中包含室内台阶。

通过向 avoid 参数传递多项限制，可以请求避开收费路段、高速公路和轮渡的任意组合的路线。例如：

avoid=tolls|highways|ferries.

departure_time

指定首选出发时间。您可以将时间指定为自世界协调时间 (UTC) 1970 年 1 月 1 日午夜以来经过的秒数（整数）。如果指定的 departure_time 晚于 9999-12-31T23:59:59.999999999Z，则 API 会将 departure_time 回退到 9999-12-31T23:59:59.999999999Z。或者，您也可以指定 now 值，将出发时间设置为当前时间（精确到秒）。在以下两种情况下，可以指定出发时间：

• 对于出行方式为公交的请求：您可以视需要指定 departure_time 或 arrival_time。 如果未指定任何时间，则 departure_time 默认为当前时间（即出发时间默认为当前时间）。
• 对于出行方式为驾车的请求：您可以指定 departure_time，以接收考虑了路况信息的路线和行程时长（响应字段：duration_in_traffic）。departure_time 必须设置为当前时间或未来的某个时间，但不能是过去的时间。

language

返回结果时所用的语言。请注意，这仅适用于 start_address 和 end_address 中的经过地理编码的地址、distance 和 duration 字段（在路段和路段步骤中）中的本地化文本以及 html_instructions 中的操作说明，而不适用于 html_instructions 中的名称和地址，这些名称和地址采用其本地语言和文字格式。

• 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
• 如果未提供 language，API 会尝试使用 Accept-Language 标头中指定的首选语言。
• 该 API 会尽力提供用户和当地人都能看懂的街道地址。为实现此目标，它会以本地语言返回街道地址，并在必要时将其音译为用户可读的文字，同时遵循首选语言。所有其他地址均以首选语言返回。所有地址组成部分均以同一种语言返回，该语言是从第一个组成部分中选择的。
• 如果首选语言中没有名称，API 会使用最接近的匹配项。
• 首选语言对 API 选择返回的结果集以及返回顺序有轻微影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或在一种语言中有效但在另一种语言中无效的同义词。例如，utca 和 tér 在匈牙利语中是“街道”的同义词。

模式

在计算距离和路线时，您可以指定要使用的交通方式。默认情况下，系统会使用 driving 模式。 默认情况下，系统会计算行车路线。支持以下出行方式：

• driving（默认）表示使用道路网的标准行车路线或距离。
• walking 请求经由步道和人行道（如有）的步行路线或距离。
• bicycling - 用于请求经由自行车道和首选街道（如有）的骑车路线或距离。
• transit - 用于请求经由公交路线（如有）的路线或距离。如果您将出行方式设置为公交，则可以选择指定 departure_time 或 arrival_time。如果未指定任何时间，则 departure_time 默认为当前时间（即出发时间默认为当前时间）。您还可以选择添加 transit_mode 和/或 transit_routing_preference。公交行程最多可显示过去 7 天或未来 100 天的信息，具体取决于数据提供商提供的公交信息。公交时刻表经常发生变化，可用的公交行程可能会随时间而变化，因此无法保证提前很久预测的结果始终一致。

区域

地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（代表“大不列颠及北爱尔兰联合王国”）。

traffic_model

指定计算交通时间时要使用的假设条件。此设置会影响响应中返回到 duration_in_traffic 字段的值，该值包含根据历史平均数据预测的交通时间。只有在请求中包含 departure_time 的行车路线中，才能指定 traffic_model 参数。此参数的可用值如下：

• best_guess（默认）- 表示返回的 duration_in_traffic 应该是最准确的行程时间估算值（根据已知的历史路况信息和实时路况信息得出）。departure_time 越接近当前时间，实时路况信息就越重要。
• pessimistic 表示返回的 duration_in_traffic 在大多数日子里应该长于实际行程时间，但偶尔路况信息特别糟糕的时候，实际行程时间可能会超过该值。
• optimistic 表示返回的 duration_in_traffic 在大多数日子里应该短于实际行程时间，但偶尔路况信息特别理想的时候，实际行程时间可能会小于该值。

对于绝大多数用例，best_guess 的默认值将提供最实用的预测。由于 best_guess 预测模型整合实时路况信息的方式，best_guess 行程时间预测结果可能会短于 optimistic，也可能会长于 pessimistic。

transit_mode

指定一种或多种首选公共交通方式。此参数只能为公共交通路线指定。该参数支持以下实参：

• bus 表示计算出的路线应首选公交出行。
• subway 表示计算出的路线应首选地铁出行。
• train 表示计算出的路线应首选火车出行。
• tram 表示计算出的路线应首选有轨电车和轻轨出行。
• rail 表示计算出的路线应首选火车、有轨电车、轻轨和地铁出行。这相当于 transit_mode=train|tram|subway。

transit_routing_preference

指定公交路线的偏好设置。利用此参数，您可以自定义调整所返回的选项，而不是接受 API 选择的默认最佳路线。此参数只能为公交路线指定。该参数支持以下实参：

• less_walking 表示计算出的路线应首选步行距离较短的路线。
• fewer_transfers 表示计算出的路线应首选换乘次数较少的路线。

个单元

指定显示结果时要使用的单位制。

路线查询结果在距离字段中包含可能向用户显示的文本，用于指示路线中特定“步骤”的距离。默认情况下，此文本使用出发地所在国家或地区的单位制。

例如，从“伊利诺伊州芝加哥市”到“安大略省多伦多市”的路线结果将以英里显示，反向路线结果则以公里显示。您可以替换此单位制，只需在请求的 units 参数中明确设置一种单位制，并传递以下任一值即可：

• metric 指定使用公制。文本距离以公里和米为单位返回。
• imperial 指定使用英制。 返回的文本距离使用英里和英尺。

途经点

指定一个中间位置数组，这些位置将作为途经点或停靠点包含在起点和终点之间的路线中。航点通过使路线经过指定位置来改变路线。该 API 支持以下出行方式的航点：驾车、步行和骑车，不支持公交。您可以提供一个或多个位置（以地点 ID、地址或纬度/经度坐标的形式），并使用竖线字符（| 或 %7C）分隔。默认情况下，路线服务会按所提供航点的指定顺序计算路线。解析航点值的优先级顺序为：地点 ID、纬度/经度坐标、地址。

• 如果您传递地点 ID，则必须为其添加 place_id: 前缀。 您可以从 Geocoding API 和 Places API（包括地点自动补全）检索地点 ID。如需查看使用来自地点自动补全服务的地点 ID 的示例，请参阅地点自动补全和路线。如需详细了解地点 ID，请参阅地点 ID 概览。
  为了提高效率和准确性，请尽可能使用地点 ID。这些 ID 像纬度/经度值对一样具有唯一性，可为路线规划提供地理编码优势，例如接入点和交通变量。与地址不同，ID 不需要服务执行搜索或发出中间请求来获取地点详情；因此，性能更佳。
• 如果您传递经纬度坐标，这些值会直接发送到前端服务器，以便在不进行地理编码的情况下计算路线。这些点会沿实际道路，可能无法提供应用所需的准确性。如果您确信这些值确实指定了应用进行路线规划所需的点，而无需考虑可能的接入点或其他地理编码详细信息，请使用坐标。确保使用英文逗号 (%2C) 而非空格 (%20) 分隔纬度和经度值。
• 如果您传递的是地址，路线服务会对该字符串进行地理编码，并将其转换为纬度/经度坐标，以计算路线。如果地址值不明确，该值可能会触发搜索，以消除与类似地址的歧义。例如，“1st Street”可以是完整值，也可以是“1st street NE”或“1st St SE”的部分值。此结果可能与 Geocoding API 返回的结果不同。您可以使用地点 ID 来避免可能的误解。
• 或者，您也可以使用编码多段线算法提供一组编码点。您会发现，编码集对于大量航点非常有用，因为网址会明显缩短。所有网络服务的网址长度上限均为 16384 个字符。
  • 编码多段线必须以 enc: 为前缀，后跟英文冒号 (:)。例如：waypoints=enc:gfo}EtohhU:。
  • 您还可以添加多条经过编码的多段线，并用竖线字符 (|) 分隔。例如，waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:

使用停靠航点和经停航点影响路线

对于请求中的每个航点，路线响应都会向 legs 数组附加一个条目，以提供该行程路段中经停点的详细信息。

如果您想使用航点影响路线，但不添加经停点，请为航点添加前缀 via:。带有 via: 前缀的航点不会向 legs 数组添加条目，但会使行程经过该航点。

以下网址修改了上一个请求，使行程经过 Lexington，但不停留：

https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

在根据用户在地图上拖动航点的操作创建路线时，via: 前缀最有效。这样，用户就可以实时查看最终路线，并有助于确保将航点放置在 Directions API 可访问的位置。

优化您的路径点

默认情况下，路线服务会按所提供航点的指定顺序计算途经这些航点的路线。或者，您也可以在 waypoints 参数中传递 optimize:true 作为第一个实参，以便路线服务按照更高效的顺序重新排列这些航点，从而对提供的路线进行优化。（这种优化用于解决旅行推销员问题）。行程时间是主要因素且进行了优化，但在确定哪条路线最高效时，可以将距离、转弯次数及许多其他因素考虑在内。所有航点都必须是停靠点，以便路线服务优化路线。

如果您指示路线服务对航点顺序进行优化，那么系统将在路线对象的 waypoint_order 字段中返回这些航点的顺序。waypoint_order 字段返回的值从零开始。

以下示例使用路线优化功能计算从南澳大利亚州阿德莱德到南澳大利亚州每个主要葡萄酒产区的公路行程。

https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

检查计算出的路线会发现，计算时会按以下航点顺序使用航点：

"waypoint_order": [ 3, 2, 0, 1 ]

后续步骤

路线示例

• 出行方式
• 路况信息
• 航点和航点优化
• 路线限制
• 单位制
• 区域偏向
• 位置修饰符

路线响应

• DirectionsResponse
• DirectionsRoute
• DirectionsLeg
• DirectionsStep 和 DirectionsPolyline
• DirectionsTransitDetails
• DirectionsStatus
• DirectionsGeocodedWaypoint