通过调用 computeRouteMatrix 方法 (REST) 或流式传输 ComputeRouteMatrix 方法 (gRPC),使用 Routes API 计算多个出发地和目的地的路线的距离和时长。
给定出发地和目的地列表,该方法会计算从每个出发地到每个目的地结束的路线的距离和时长。
获取公交路线矩阵
您还可以计算公交的路线矩阵。如需查看示例,请参阅获取公交路线矩阵。
请求限制
计算路线矩阵方法对使用地址或地点 ID 的航点以及元素实施以下请求限制。元素是路线矩阵中每个出发地与目的地之间的路线,因此元素数量为出发地数量乘以目的地数量。例如,如果您有 10 个出发地和 10 个目的地,则会有 100 个元素:
对于不是
TRANSIT
路由的路由,元素数不能超过 625。如果您指定
TRANSIT
路由,则元素数不能超过 100。如果您指定
TRAFFIC_AWARE_OPTIMAL
,则元素数量不得超过 100。如需详细了解TRAFFIC_AWARE_OPTIMAL
,请参阅指定如何以及是否纳入流量数据。如果您使用地址或地点 ID 指定出发地或目的地,使用此方式最多可以指定总共 50 个。
响应错误
计算路线矩阵方法的一项功能是,可以针对整个响应或各个响应元素返回错误。例如,如果请求的格式不正确(例如,请求的来源为零),则整个响应都会包含错误。
但是,如果响应中的部分元素存在错误(例如,无法针对出发地和目的地的组合计算路线),则只有受错误影响的元素才会返回错误代码。
gRPC 流结果
ComputeRouteMatrix gRPC 方法接受出发地和目的地的列表,并返回包含每个出发地和目的地组合的路线信息的数据流。由于结果以数据流的形式返回,因此您不必等到所有可能的路线组合计算出来后,便可开始处理结果。
流返回的元素不一定会按任何顺序返回。因此,每个响应元素都包含一个 origin_index
和 destination_index
。对于请求指定的出发地和目的地,对于给定元素,路线出发地等同于 origins[origin_index]
,路线目的地等同于 destinations[destination_index]
。这些数组从零索引。请务必存储出发地和目的地列表顺序。
计算路线矩阵样本
在 HTTP 请求中使用 computeRouteMatrix 方法计算路线矩阵。
HTTP 示例
以下示例展示了 computeRouteMatrix
HTTP 请求。在此示例中,您:
指定由两个起点和两个终点路标组成的数组。该方法会计算从每个出发地到每个目的地的路线,因此响应包含四条路线。
在该数组中,第一个元素的索引为 0,第二个元素的索引为 1,依此类推。
添加响应字段掩码,以指定要返回的响应 (REST) 或 ComputeRoutesResponse (gRPC) 的哪些字段。在此示例中,将请求配置为为每个路由返回
originIndex
、destinationIndex
、duration
、distanceMeters
、status
和condition
。如需了解详情,请参阅选择要返回的字段。
curl -X POST -d '{ "origins": [ { "waypoint": { "location": { "latLng": { "latitude": 37.420761, "longitude": -122.081356 } } }, "routeModifiers": { "avoid_ferries": true} }, { "waypoint": { "location": { "latLng": { "latitude": 37.403184, "longitude": -122.097371 } } }, "routeModifiers": { "avoid_ferries": true} } ], "destinations": [ { "waypoint": { "location": { "latLng": { "latitude": 37.420999, "longitude": -122.086894 } } } }, { "waypoint": { "location": { "latLng": { "latitude": 37.383047, "longitude": -122.044651 } } } } ], "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \ 'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'
响应包含所有出发地和目的地航点组合的四条可能的路线。
使用 originIndex
和 destinationIndex
响应字段标识响应中的每条路由。例如,响应中的 originIndex
为 1 对应于根据请求中 origins
数组索引 1 处的航点计算得出的路线。
[ { "originIndex": 0, "destinationIndex": 0, "status": {}, "distanceMeters": 822, "duration": "160s", "condition": "ROUTE_EXISTS" }, { "originIndex": 1, "destinationIndex": 0, "status": {}, "distanceMeters": 2919, "duration": "361s", "condition": "ROUTE_EXISTS" }, { "originIndex": 1, "destinationIndex": 1, "status": {}, "distanceMeters": 5598, "duration": "402s", "condition": "ROUTE_EXISTS" }, { "originIndex": 0, "destinationIndex": 1, "status": {}, "distanceMeters": 7259, "duration": "712s", "condition": "ROUTE_EXISTS" } ]
gRPC 示例
如需查看 gRPC 请求示例,请参阅 gRPC 请求示例中的示例。该页面上的 Java 示例同时调用了“计算路线”和“计算路线矩阵”。