calculateRouteMatrix method

Use CalculateRouteMatrix to compute results for all pairs of Origins to Destinations. Each row corresponds to one entry in Origins. Each entry in the row corresponds to the route from that entry in Origins to an entry in Destinations positions.

For more information, see Calculate route matrix in the Amazon Location Service Developer Guide.

May throw AccessDeniedException. May throw InternalServerException. May throw ThrottlingException. May throw ValidationException.

Parameter destinations : List of destinations for the route in World Geodetic System (WGS 84) format: [longitude, latitude]. The maximum number of destinations depends on the routing boundary configuration:

• With RoutingBoundary.Geometry set: maximum 500 destinations
• With RoutingBoundary.Unbounded set to true: maximum 100 destinations
• For GrabMaps customers in ap-southeast-1 and ap-southeast-5: maximum 350 destinations

The total matrix size (origins × destinations) must not exceed:

• With RoutingBoundary.Geometry: 160,000
• With RoutingBoundary.Unbounded: 100
• For GrabMaps customers in ap-southeast-1 and ap-southeast-5: 122,500

Parameter origins : List of origins for the route in World Geodetic System (WGS 84) format: [longitude, latitude]. The maximum number of origins depends on the routing boundary configuration:

• With RoutingBoundary.Geometry set: maximum 500 origins
• With RoutingBoundary.Unbounded set to true: maximum 15 origins
• For GrabMaps customers in ap-southeast-1 and ap-southeast-5: maximum 350 origins

The total matrix size (origins × destinations) must not exceed:

• With RoutingBoundary.Geometry: 160,000
• With RoutingBoundary.Unbounded: 100
• For GrabMaps customers in ap-southeast-1 and ap-southeast-5: 122,500

Parameter allow : Features that are allowed while calculating a route.

Parameter avoid : Features that are avoided while calculating a route. Avoidance is on a best-case basis. If an avoidance can't be satisfied for a particular case, it violates the avoidance and the returned response produces a notice for the violation. For GrabMaps customers, ap-southeast-1 and ap-southeast-5 regions support only TollRoads, Ferries, and ControlledAccessHighways.

Parameter departNow : Uses the current time as the time of departure.

Parameter departureTime : Time of departure from the origin.

Time format:YYYY-MM-DDThh:mm:ss.sssZ | YYYY-MM-DDThh:mm:ss.sss+hh:mm

Examples:

2020-04-22T17:57:24Z

2020-04-22T17:57:24+02:00

Parameter exclude : Features to be strictly excluded while calculating the route. Not supported in ap-southeast-1 and ap-southeast-5 regions for GrabMaps customers.

Parameter key : Optional: The API key to be used for authorization. Either an API key or valid SigV4 signature must be provided when making a request.

Parameter optimizeRoutingFor : Controls the trade-off between finding the shortest travel time (FastestRoute) and the shortest distance (ShortestRoute) when calculating reachable areas.

Default value: FastestRoute

Parameter routingBoundary : Boundary within which the matrix is to be calculated. All data, origins and destinations outside the boundary are considered invalid. For GrabMaps customers, ap-southeast-1 and ap-southeast-5 regions support only Unbounded set to true.

Default value: Unbounded set to true

Parameter traffic : Traffic related options. Not supported in ap-southeast-1 and ap-southeast-5 regions for GrabMaps customers.

Parameter travelMode : Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility. For GrabMaps customers, ap-southeast-1 and ap-southeast-5 regions support only Car, Pedestrian, and Scooter.

Default value: Car

Parameter travelModeOptions : Travel mode related options for the provided travel mode. Not supported in ap-southeast-1 and ap-southeast-5 regions for GrabMaps customers.

Future<CalculateRouteMatrixResponse> calculateRouteMatrix({
  required List<RouteMatrixDestination> destinations,
  required List<RouteMatrixOrigin> origins,
  RouteMatrixAllowOptions? allow,
  RouteMatrixAvoidanceOptions? avoid,
  bool? departNow,
  String? departureTime,
  RouteMatrixExclusionOptions? exclude,
  String? key,
  RoutingObjective? optimizeRoutingFor,
  RouteMatrixBoundary? routingBoundary,
  RouteMatrixTrafficOptions? traffic,
  RouteMatrixTravelMode? travelMode,
  RouteMatrixTravelModeOptions? travelModeOptions,
}) async {
  final $query = <String, List<String>>{
    if (key != null) 'key': [key],
  };
  final $payload = <String, dynamic>{
    'Destinations': destinations,
    'Origins': origins,
    if (allow != null) 'Allow': allow,
    if (avoid != null) 'Avoid': avoid,
    if (departNow != null) 'DepartNow': departNow,
    if (departureTime != null) 'DepartureTime': departureTime,
    if (exclude != null) 'Exclude': exclude,
    if (optimizeRoutingFor != null)
      'OptimizeRoutingFor': optimizeRoutingFor.value,
    if (routingBoundary != null) 'RoutingBoundary': routingBoundary,
    if (traffic != null) 'Traffic': traffic,
    if (travelMode != null) 'TravelMode': travelMode.value,
    if (travelModeOptions != null) 'TravelModeOptions': travelModeOptions,
  };
  final response = await _protocol.sendRaw(
    payload: $payload,
    method: 'POST',
    requestUri: '/v2/route-matrix',
    queryParams: $query,
    exceptionFnMap: _exceptionFns,
  );
  final $json = await _s.jsonFromResponse(response);
  return CalculateRouteMatrixResponse(
    errorCount: ($json['ErrorCount'] as int?) ?? 0,
    routeMatrix: (($json['RouteMatrix'] as List?) ?? const [])
        .nonNulls
        .map((e) => (e as List)
            .nonNulls
            .map((e) => RouteMatrixEntry.fromJson(e as Map<String, dynamic>))
            .toList())
        .toList(),
    routingBoundary: RouteMatrixBoundary.fromJson(
        ($json['RoutingBoundary'] as Map<String, dynamic>?) ??
            const <String, dynamic>{}),
    pricingBucket: _s.extractHeaderStringValue(
        response.headers, 'x-amz-geo-pricing-bucket')!,
  );
}