获取路由矩阵

路线矩阵是一个二维路线信息数组,其中行对应于出发地,列对应于目的地。给定一个出发地和目的地列表,Route Matrix 类会计算从每个出发地出发并到达每个目的地的路线的距离和时长。使用 Route Matrix 类计算多个出发地和目的地的路线距离和时长。

请求限制

RouteMatrix.computeRouteMatrix() 方法针对使用地址或 Place 实例的途径点以及项目强制执行以下请求限制。项是指路线矩阵中每个出发地与目的地之间的路线,因此项数等于出发地数量乘以目的地数量。例如,如果您有 10 个出发地和 10 个目的地,则有 100 个项目:

  • 对于非 TRANSIT 路线,项目数量不得超过 625。
  • 如果您指定了 TRANSIT 路线,则商品数量不得超过 100。
  • 如果您指定了 TRAFFIC_AWARE_OPTIMAL,则商品数量不得超过 100。
  • 如果您使用地址或 Place 实例指定起点或终点,则最多可以指定 50 个。

路线矩阵请求示例

以下示例展示了 ComputeRouteMatrixRequest。此示例执行以下操作:

  • 显示了如何指定包含两个出发地和两个目的地的航点数组。该方法会计算从每个出发地到每个目的地的路线,因此响应包含四条路线。
    在数组中,第一个元素的索引为 0,第二个元素的索引为 1,依此类推。
  • 指定要返回的字段。在此示例中,配置请求以针对每个路线返回 durationMillisdistanceMeterscondition
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'],
    

确定要使用的字段掩码

以下示例展示了如何确定要使用的字段,并为其构建字段掩码:

  1. 使用 ['*'] 的字段掩码请求所有字段
  2. RouteMatrixItem 类中查看所需字段的层次结构
  3. 使用上一步中显示的字段层次结构,构建字段掩码,格式如下:

    topLevelField[.secondLevelField][.thirdLevelField][...]

例如,对于以下 RouteMatrixItem

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },
    

如果您只想返回 RouteMatrixItemtollInfo 字段,则字段掩码如下所示:

fields: ['travelAdvisory.tollInfo']

如果您想改为请求估计的燃料消耗量,则字段掩码如下所示:

fields: ['travelAdvisory.fuelConsumptionMicroliters']

如果您想同时请求这两个字段,则字段掩码如下所示:

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

如果您想请求获取全套旅行建议,您的字段遮盖如下所示:

fields: ['travelAdvisory']