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.

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.

Type: RouteMatrixAvoidanceOptions object

Required: No

DepartNow

Uses the current time as the time of departure.

Type: Boolean

Required: No

DepartureTime

Time of departure from thr 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.

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. See Amazon Location's pricing page for more information.

Type: Array of RouteMatrixDestination objects

Array Members: Minimum number of 1 item.

Required: Yes

Exclude

Features to be strictly excluded while calculating the route.

Type: RouteMatrixExclusionOptions object

Required: No

OptimizeRoutingFor

Specifies the optimization criteria for calculating a route.

Default Value: FastestRoute

Type: String

Valid Values: FastestRoute | ShortestRoute

Required: No

Origins

The position in longitude and latitude for the origin.

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. See Amazon Location's pricing page for more information.

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.

Note

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

Type: RouteMatrixBoundary object

Required: Yes

Traffic

Traffic related options.

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.

Default Value: Car

Type: String

Valid Values: Car | Pedestrian | Scooter | Truck

Required: No

TravelModeOptions

Travel mode related options for the provided travel mode.

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 request routing boundary was set as AutoCircle, 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 Errors.

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.

HTTP Status Code: 400