获取路由矩阵

通过调用 computeRouteMatrix 方法 (REST) 或流式处理 ComputeRouteMatrix 方法 (gRPC),使用 Routes API 针对多个出发地和目的地计算路线的距离和时长。

在给定出发地和目的地列表后,此方法会计算以每个出发地为起点、终点为终点的路线的距离和时长。

获取公交路线矩阵

您还可以计算公交的路线矩阵。如需查看示例,请参阅获取公交的路线矩阵

请求限制

计算路线矩阵方法针对使用地址或 placeID 的航点以及元素强制实施以下请求限制。元素是路线矩阵中每个出发地与目的地之间的路线,因此元素数量是出发地数量乘以目的地数量。例如,如果您有 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,依此类推。

  • 添加响应字段掩码,用于指定要返回的 response (REST) 或 ComputeRoutesResponse (gRPC) 的字段。在此示例中,请将请求配置为为每个路由返回 originIndexdestinationIndexdurationdistanceMetersstatuscondition。如需了解详情,请参阅选择要返回的字段

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'

响应包含所有出发地航点和目的地航点组合的四种可能路线。

使用 originIndexdestinationIndex 响应字段标识响应中的每条路由。例如,响应中的 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 示例同时调用“计算路线”和“计算路线矩阵”。

客户端 JavaScript 示例

const reqBody = {
   "origins": [
       {
         "waypoint": {
           "location": {
             "latLng": {
               "latitude": 37.420761,
               "longitude": -122.081356
             }
           }
         }
       },
       {
         "waypoint": {
           "location": {
             "latLng": {
               "latitude": 37.403184,
               "longitude": -122.097371
             }
           }
         }
       }
     ],
     "destinations": [
       {
         "waypoint": {
           "location": {
             "latLng": {
               "latitude": 37.420999,
               "longitude": -122.086894
             }
           }
         }
       },
       {
         "waypoint": {
           "location": {
             "latLng": {
               "latitude": 37.383047,
               "longitude": -122.044651
             }
           }
         }
       }
     ],
   "travelMode": "DRIVE",
   "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
};
fetch("https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix", {
   method: "POST",
   headers: {
       "Content-Type": "application/json",
       "X-Goog-Api-Key": "YOUR_API_KEY",
       "X-Goog-FieldMask": "*"
   },
   body: JSON.stringify(reqBody)
}).then((response) => {
   return response.json();
}).then((data) => {
   if(data.hasOwnProperty("error")){
       console.log(data.error);
   } else {
       console.log(data);
   }
}).catch((error) => {
   console.log(error)
});