Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CalculateRouteMatrix

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.

Request Syntax


POST /route-matrix?key=Key HTTP/1.1
Content-type: application/json

{
   "Allow": { 
      "Hot": boolean,
      "Hov": boolean
   },
   "Avoid": { 
      "Areas": [ 
         { 
            "Geometry": { 
               "BoundingBox": [ number ],
               "Polygon": [ 
                  [ 
                     [ number ]
                  ]
               ],
               "PolylinePolygon": [ "string" ]
            }
         }
      ],
      "CarShuttleTrains": boolean,
      "ControlledAccessHighways": boolean,
      "DirtRoads": boolean,
      "Ferries": boolean,
      "TollRoads": boolean,
      "TollTransponders": boolean,
      "TruckRoadTypes": [ "string" ],
      "Tunnels": boolean,
      "UTurns": boolean,
      "ZoneCategories": [ 
         { 
            "Category": "string"
         }
      ]
   },
   "DepartNow": boolean,
   "DepartureTime": "string",
   "Destinations": [ 
      { 
         "Options": { 
            "AvoidActionsForDistance": number,
            "Heading": number,
            "Matching": { 
               "NameHint": "string",
               "OnRoadThreshold": number,
               "Radius": number,
               "Strategy": "string"
            },
            "SideOfStreet": { 
               "Position": [ number ],
               "UseWith": "string"
            }
         },
         "Position": [ number ]
      }
   ],
   "Exclude": { 
      "Countries": [ "string" ]
   },
   "OptimizeRoutingFor": "string",
   "Origins": [ 
      { 
         "Options": { 
            "AvoidActionsForDistance": number,
            "Heading": number,
            "Matching": { 
               "NameHint": "string",
               "OnRoadThreshold": number,
               "Radius": number,
               "Strategy": "string"
            },
            "SideOfStreet": { 
               "Position": [ number ],
               "UseWith": "string"
            }
         },
         "Position": [ number ]
      }
   ],
   "RoutingBoundary": { 
      "Geometry": { 
         "AutoCircle": { 
            "Margin": number,
            "MaxRadius": number
         },
         "BoundingBox": [ number ],
         "Circle": { 
            "Center": [ number ],
            "Radius": number
         },
         "Polygon": [ 
            [ 
               [ number ]
            ]
         ]
      },
      "Unbounded": boolean
   },
   "Traffic": { 
      "FlowEventThresholdOverride": number,
      "Usage": "string"
   },
   "TravelMode": "string",
   "TravelModeOptions": { 
      "Car": { 
         "LicensePlate": { 
            "LastCharacter": "string"
         },
         "MaxSpeed": number,
         "Occupancy": number
      },
      "Scooter": { 
         "LicensePlate": { 
            "LastCharacter": "string"
         },
         "MaxSpeed": number,
         "Occupancy": number
      },
      "Truck": { 
         "AxleCount": number,
         "GrossWeight": number,
         "HazardousCargos": [ "string" ],
         "Height": number,
         "KpraLength": number,
         "Length": number,
         "LicensePlate": { 
            "LastCharacter": "string"
         },
         "MaxSpeed": number,
         "Occupancy": number,
         "PayloadCapacity": number,
         "Trailer": { 
            "TrailerCount": number
         },
         "TruckType": "string",
         "TunnelRestrictionCode": "string",
         "WeightPerAxle": number,
         "WeightPerAxleGroup": { 
            "Quad": number,
            "Quint": number,
            "Single": number,
            "Tandem": number,
            "Triple": number
         },
         "Width": number
      }
   }
}

URI Request Parameters

The request uses the following URI parameters.

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.

Length Constraints: Minimum length of 0. Maximum length of 1000.

Request Body

The request accepts the following data in JSON format.

Allow

Features that are allowed while calculating a route.

Type: RouteMatrixAllowOptions object

Required: No

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.

Type: RouteMatrixAvoidanceOptions object

Required: No

DepartNow

Uses the current time as the time of departure.

Type: Boolean

Required: No

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

Type: String

Pattern: ([1-2][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]{0,9})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])

Required: No

Destinations

List of destinations for the route in World Geodetic System (WGS 84) format: [longitude, latitude].

Note

Route calculations are billed for each origin and destination pair. If you use a large matrix of origins and destinations, your costs will increase accordingly. For more information, see Routes pricing in the Amazon Location Service Developer Guide.

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

Type: Array of RouteMatrixDestination objects

Array Members: Minimum number of 1 item.

Required: Yes

Exclude

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

Type: RouteMatrixExclusionOptions object

Required: No

OptimizeRoutingFor

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

Default value: FastestRoute

Type: String

Valid Values: FastestRoute | ShortestRoute

Required: No

Origins

List of origins for the route in World Geodetic System (WGS 84) format: [longitude, latitude].

Note

Route calculations are billed for each origin and destination pair. Using a large amount of Origins in a request can lead you to incur unexpected charges. For more information, see Routes pricing in the Amazon Location Service Developer Guide.

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

Type: Array of RouteMatrixOrigin objects

Array Members: Minimum number of 1 item.

Required: Yes

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

Note

When AutoCircle is set in the request, the response routing boundary will return Circle derived from the AutoCircle settings.

Type: RouteMatrixBoundary object

Required: No

Traffic

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

Type: RouteMatrixTrafficOptions object

Required: No

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

Type: String

Valid Values: Car | Pedestrian | Scooter | Truck

Required: No

TravelModeOptions

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

Type: RouteMatrixTravelModeOptions object

Required: No

Response Syntax


HTTP/1.1 200
x-amz-geo-pricing-bucket: PricingBucket
Content-type: application/json

{
   "ErrorCount": number,
   "RouteMatrix": [ 
      [ 
         { 
            "Distance": number,
            "Duration": number,
            "Error": "string"
         }
      ]
   ],
   "RoutingBoundary": { 
      "Geometry": { 
         "AutoCircle": { 
            "Margin": number,
            "MaxRadius": number
         },
         "BoundingBox": [ number ],
         "Circle": { 
            "Center": [ number ],
            "Radius": number
         },
         "Polygon": [ 
            [ 
               [ number ]
            ]
         ]
      },
      "Unbounded": boolean
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

PricingBucket: The pricing bucket for which the query is charged at.

The following data is returned in JSON format by the service.

ErrorCount

The count of error results in the route matrix. If this number is 0, all routes were calculated successfully.

Type: Integer

Valid Range: Minimum value of 0.

RouteMatrix

The calculated route matrix containing the results for all pairs of Origins to Destination positions. 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 Destination positions.

Type: Array of arrays of RouteMatrixEntry objects

RoutingBoundary

Boundary within which the matrix is to be calculated. All data, origins and destinations outside the boundary are considered invalid.

Note

When AutoCircle is set in the request, the response routing boundary will return Circle derived from the AutoCircle settings.

Type: RouteMatrixBoundary object

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You don't have sufficient access to perform this action.

HTTP Status Code: 403

InternalServerException

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by an AWS service.

FieldList: The field where the invalid entry was detected.
Reason: A message with the reason for the validation exception error.

HTTP Status Code: 400