通过 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

注意：网址必须经过正确编码才有效，并且对于所有 Web 服务，网址长度不得超过 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）。
  注意：为提高效率和准确性，请尽可能使用地点 ID。这些 ID 像纬度/经度值对一样具有唯一性，并可为路线规划提供地理编码优势，例如接入点和交通变量。与地址不同，ID 不需要服务执行搜索或发出中间请求来获取地点详情，因此性能更佳。

可选参数

• 替代方案

  如果设置为 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 必须设置为当前时间或未来的某个时间，但不能是过去的时间。
  注意：如果未指定出发时间，则系统会根据道路网和与时间无关的平均路况信息来选择路线和时长。受道路网变化、平均路况信息更新以及服务的分布式性质的影响，给定请求的结果可能会随时间的推移而发生变化。此外，在时间或频率不受限制的情况下，即使两条路线几乎相同，结果还是有可能不同。
  注意：如果距离矩阵请求在 mode=driving 时指定 departure_time，则每个请求最多只能包含 100 个元素。出发地数量与目的地数量的乘积便是元素数量。

• 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 字段的值，该值包含根据历史平均数据预测的交通时间。traffic_model 参数只能在请求包含 departure_time 的行车路线中指定。此参数的可用值如下：

  • 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 指定使用英制。 返回的文本距离使用英里和英尺。
  请注意：此单位制设置仅影响距离字段中显示的文本。距离字段也包含始终以米为单位的值。

• 途经点

  注意：使用超过 10 个航点（介于 11 到 25 之间）或航点优化的请求会以较高费率结算。 详细了解 Google Maps Platform 产品的结算方式。

  指定一个中间位置数组，这些位置将作为经停点或中途停留点包含在起点和终点之间的路线中。航点通过使路线经过指定位置来改变路线。该 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 数组添加条目，但会使行程经过该航点。

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

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

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

  注意：如果使用 via: 前缀来避免停靠，则生成的路线将会严格解读航点。如果 Directions API 无法创建途经该经停点的路线，这种解读可能导致路线严重绕行，或者响应状态代码中出现 ZERO_RESULTS。

  优化您的路径点

  默认情况下，路线服务会按所提供航点的指定顺序计算途经这些航点的路线。或者，您也可以在航点参数中传递 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 ]
  

  注意：使用航点优化的请求会以较高费率结算。 详细了解 Google Maps Platform 产品的结算方式。

后续步骤

路线示例

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

路线响应

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