路线矩阵是一个二维路线信息数组,其中行对应于出发地,列对应于目的地。给定一个出发地和目的地列表,Route Matrix 类会计算从每个出发地出发并到达每个目的地的路线的距离和时长。使用 Route Matrix 类计算多个出发地和目的地的路线距离和时长。
请求限制
RouteMatrix.computeRouteMatrix()
方法针对使用地址或 Place 实例的途径点以及项目强制执行以下请求限制。项是指路线矩阵中每个出发地与目的地之间的路线,因此项数等于出发地数量乘以目的地数量。例如,如果您有 10 个出发地和 10 个目的地,则有 100 个项目:
- 对于非
TRANSIT
路线,项目数量不得超过 625。 - 如果您指定了
TRANSIT
路线,则商品数量不得超过 100。 - 如果您指定了
TRAFFIC_AWARE_OPTIMAL
,则商品数量不得超过 100。 - 如果您使用地址或 Place 实例指定起点或终点,则最多可以指定 50 个。
路线矩阵请求示例
以下示例展示了 ComputeRouteMatrixRequest
。此示例执行以下操作:
- 显示了如何指定包含两个出发地和两个目的地的航点数组。该方法会计算从每个出发地到每个目的地的路线,因此响应包含四条路线。
在数组中,第一个元素的索引为 0,第二个元素的索引为 1,依此类推。 - 指定要返回的字段。在此示例中,配置请求以针对每个路线返回
durationMillis
、distanceMeters
和condition
。
const request = { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: google.maps.TravelMode.DRIVING, units: google.maps.UnitSystem.METRIC, fields: ['durationMillis', 'distanceMeters', 'condition'], };
响应包含所有起点和目的地途经点的组合对应的四条可能路线,如下例所示:
"matrix": { "rows": [ { "items": [ { "condition": "ROUTE_EXISTS", "distanceMeters": 202587, "durationMillis": 10040000 }, { "condition": "ROUTE_EXISTS", "distanceMeters": 252734, "durationMillis": 12240000 } ] }, { "items": [ { "condition": "ROUTE_EXISTS", "distanceMeters": 166135, "durationMillis": 6596000 }, { "condition": "ROUTE_EXISTS", "distanceMeters": 216282, "durationMillis": 8797000 } ] } ] }
使用出发地和目的地索引在二维数组中查找相应的 RouteMatrixItem
,以标识结果中的每条路线。例如,描述从请求中索引为 1 的出发地到索引为 0 的目的地计算出的路线的 RouteMatrixItem
将位于 RouteMatrix.rows
数组的第 2 个元素和 RouteMatrixRow.items
数组的第 1 个元素中。
以下代码段展示了如何识别 RouteMatrixItem
以查找特定起点和目的地的路线:
// Find the route for origin 'x' and destination 'y'. const {matrix} = await RouteMatrix.computeRouteMatrix(request); const myRouteMatrixItem = matrix.rows[x].items[y];
选择要返回的字段
请求路线矩阵时,您必须使用字段掩码来指定响应应返回哪些信息。
使用字段掩码还可以确保您不会请求不必要的数据,这有助于缩短响应延迟时间,并避免返回系统不需要的信息。
通过设置
ComputeRoutesMatrixRequest.fields
属性来指定所需的字段列表,如以下代码段所示:
fields: ['durationMillis', 'distanceMeters', 'condition'],
确定要使用的字段掩码
以下示例展示了如何确定要使用的字段,并为其构建字段掩码:
- 使用
['*']
的字段掩码请求所有字段。 - 在
RouteMatrixItem
类中查看所需字段的层次结构。 使用上一步中显示的字段层次结构,构建字段掩码,格式如下:
topLevelField[.secondLevelField][.thirdLevelField][...]
例如,对于以下 RouteMatrixItem
:
"travelAdvisory": { "fuelConsumptionMicroliters": 0, "tollInfo": { "estimatedPrices": [ { "currencyCode": "USD", "units": 4, "nanos": 400000000 } ] } },
如果您只想返回 RouteMatrixItem
的 tollInfo
字段,则字段掩码如下所示:
fields: ['travelAdvisory.tollInfo']
如果您想改为请求估计的燃料消耗量,则字段掩码如下所示:
fields: ['travelAdvisory.fuelConsumptionMicroliters']
如果您想同时请求这两个字段,则字段掩码如下所示:
fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']
如果您想请求获取全套旅行建议,您的字段遮盖如下所示:
fields: ['travelAdvisory']