# Amazon Location Service Routes V2 The following actions are supported by Amazon Location Service Routes V2: + [CalculateIsolines](API_CalculateIsolines.md) + [CalculateRouteMatrix](API_CalculateRouteMatrix.md) + [CalculateRoutes](API_CalculateRoutes.md) + [OptimizeWaypoints](API_OptimizeWaypoints.md) + [SnapToRoads](API_SnapToRoads.md) # CalculateIsolines Calculates areas that can be reached within specified time or distance thresholds from a given point. For example, you can use this operation to determine the area within a 30-minute drive of a store location, find neighborhoods within walking distance of a school, or identify delivery zones based on drive time. Isolines (also known as isochrones for time-based calculations) are useful for various applications including: + Service area visualization - Show customers the area you can serve within promised delivery times + Site selection - Analyze potential business locations based on population within travel distance + Site selection - Determine areas that can be reached within specified response times **Note** Route preferences such as avoiding toll roads or ferries are treated as preferences rather than absolute restrictions. If a viable route cannot be calculated while honoring all preferences, some may be ignored. For more information, see [Calculate isolines](https://docs.aws.amazon.com/location/latest/developerguide/calculate-isolines.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /isolines?key=Key HTTP/1.1 Content-type: application/json { "Allow": { "Hot": boolean, "Hov": boolean }, "ArrivalTime": "string", "Avoid": { "Areas": [ { "Except": [ { "BoundingBox": [ number ], "Corridor": { "LineString": [ [ number ] ], "Radius": number }, "Polygon": [ [ [ number ] ] ], "PolylineCorridor": { "Polyline": "string", "Radius": number }, "PolylinePolygon": [ "string" ] } ], "Geometry": { "BoundingBox": [ number ], "Corridor": { "LineString": [ [ number ] ], "Radius": number }, "Polygon": [ [ [ number ] ] ], "PolylineCorridor": { "Polyline": "string", "Radius": number }, "PolylinePolygon": [ "string" ] } } ], "CarShuttleTrains": boolean, "ControlledAccessHighways": boolean, "DirtRoads": boolean, "Ferries": boolean, "SeasonalClosure": boolean, "TollRoads": boolean, "TollTransponders": boolean, "TruckRoadTypes": [ "string" ], "Tunnels": boolean, "UTurns": boolean, "ZoneCategories": [ { "Category": "string" } ] }, "DepartNow": boolean, "DepartureTime": "string", "Destination": [ number ], "DestinationOptions": { "AvoidActionsForDistance": number, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "SideOfStreet": { "Position": [ number ], "UseWith": "string" } }, "IsolineGeometryFormat": "string", "IsolineGranularity": { "MaxPoints": number, "MaxResolution": number }, "OptimizeIsolineFor": "string", "OptimizeRoutingFor": "string", "Origin": [ number ], "OriginOptions": { "AvoidActionsForDistance": number, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "SideOfStreet": { "Position": [ number ], "UseWith": "string" } }, "Thresholds": { "Distance": [ number ], "Time": [ number ] }, "Traffic": { "FlowEventThresholdOverride": number, "Usage": "string" }, "TravelMode": "string", "TravelModeOptions": { "Car": { "EngineType": "string", "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number }, "Scooter": { "EngineType": "string", "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number }, "Truck": { "AxleCount": number, "EngineType": "string", "GrossWeight": number, "HazardousCargos": [ "string" ], "Height": number, "HeightAboveFirstAxle": number, "KpraLength": number, "Length": number, "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number, "PayloadCapacity": number, "TireCount": number, "Trailer": { "AxleCount": number, "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](#API_CalculateIsolines_RequestSyntax) ** An Amazon Location Service API Key with access to this action. If omitted, the request must be signed using Signature Version 4. Length Constraints: Minimum length of 0. Maximum length of 1000. ## Request Body The request accepts the following data in JSON format. ** [Allow](#API_CalculateIsolines_RequestSyntax) ** Enables special road types or features that should be considered for routing even if they might be restricted by default for the selected travel mode. These include high-occupancy vehicle and toll lanes. Type: [IsolineAllowOptions](API_IsolineAllowOptions.md) object Required: No ** [ArrivalTime](#API_CalculateIsolines_RequestSyntax) ** Determine areas from which `Destination` can be reached by this time, taking into account predicted traffic conditions and working backward to account for congestion patterns. This attribute cannot be used together with `DepartureTime` or `DepartNow`. Specified as an ISO-8601 timestamp with timezone offset. 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 ** [Avoid](#API_CalculateIsolines_RequestSyntax) ** Specifies road types, features, or areas to avoid (if possible) when calculating reachable areas. These are treated as preferences rather than strict constraints—if a route cannot be calculated without using an avoided feature, that avoidance preference may be ignored. Type: [IsolineAvoidanceOptions](API_IsolineAvoidanceOptions.md) object Required: No ** [DepartNow](#API_CalculateIsolines_RequestSyntax) ** When true, uses the current time as the departure time and takes current traffic conditions into account. This attribute cannot be used together with `DepartureTime` or `ArrivalTime`. Type: Boolean Required: No ** [DepartureTime](#API_CalculateIsolines_RequestSyntax) ** Determine areas that can be reached when departing at this time, taking into account predicted traffic conditions. This attribute cannot be used together with `ArrivalTime` or `DepartNow`. Specified as an ISO-8601 timestamp with timezone offset. 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 ** [Destination](#API_CalculateIsolines_RequestSyntax) ** An optional destination point, specified as `[longitude, latitude]` coordinates. When provided, the service calculates areas from which this destination can be reached within the specified thresholds. This reverses the usual isoline calculation to show areas that could reach your location, rather than areas you could reach from your location. Either `Origin` or `Destination` must be provided. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [DestinationOptions](#API_CalculateIsolines_RequestSyntax) ** Options that control how the destination point is matched to the road network and how routes can approach it. These options help improve travel time accuracy by accounting for real-world access to the destination. Type: [IsolineDestinationOptions](API_IsolineDestinationOptions.md) object Required: No ** [IsolineGeometryFormat](#API_CalculateIsolines_RequestSyntax) ** The format of the returned IsolineGeometry. Default value:`FlexiblePolyline` Type: String Valid Values: `FlexiblePolyline | Simple` Required: No ** [IsolineGranularity](#API_CalculateIsolines_RequestSyntax) ** Controls the detail level of the generated isolines. Higher granularity produces smoother shapes but requires more processing time and results in larger responses. Type: [IsolineGranularityOptions](API_IsolineGranularityOptions.md) object Required: No ** [OptimizeIsolineFor](#API_CalculateIsolines_RequestSyntax) ** Controls the trade-off between calculation speed and isoline precision. Choose ` FastCalculation` for quicker results with less detail, `AccurateCalculation` for more precise results, or `BalancedCalculation` for a middle ground. Default value: `BalancedCalculation` Type: String Valid Values: `AccurateCalculation | BalancedCalculation | FastCalculation` Required: No ** [OptimizeRoutingFor](#API_CalculateIsolines_RequestSyntax) ** Determines whether routes prioritize shortest travel time (`FastestRoute`) or shortest physical distance (`ShortestRoute`) when calculating reachable areas. Default value: `FastestRoute` Type: String Valid Values: `FastestRoute | ShortestRoute` Required: No ** [Origin](#API_CalculateIsolines_RequestSyntax) ** The starting point for isoline calculations, specified as `[longitude, latitude]` coordinates. For example, this could be a store location, service center, or any point from which you want to calculate reachable areas. Either `Origin` or `Destination` must be provided. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [OriginOptions](#API_CalculateIsolines_RequestSyntax) ** Options that control how the origin point is matched to the road network and how routes can depart from it. These options help improve travel time accuracy by accounting for real-world access from the origin. Type: [IsolineOriginOptions](API_IsolineOriginOptions.md) object Required: No ** [Thresholds](#API_CalculateIsolines_RequestSyntax) ** The distance or time thresholds used to determine reachable areas. You can specify up to five thresholds (which all must be the same type) to calculate multiple isolines in a single request. For example, to determine the areas that are reachable within 10 and 20 minutes of the origin, specify time thresholds of 600 and 1200 seconds. You incur a calculation charge for each threshold. Using a large number of thresholds in a request can lead to unexpected charges. For more information, see [Routes pricing](https://docs.aws.amazon.com/location/latest/developerguide/routes-pricing.html) in the *Amazon Location Service Developer Guide*. Type: [IsolineThresholds](API_IsolineThresholds.md) object Required: Yes ** [Traffic](#API_CalculateIsolines_RequestSyntax) ** Configures how real-time and historical traffic data affects isoline calculations. Traffic patterns can significantly impact reachable areas, especially during peak hours. Type: [IsolineTrafficOptions](API_IsolineTrafficOptions.md) object Required: No ** [TravelMode](#API_CalculateIsolines_RequestSyntax) ** The mode of transportation to use for calculations. This affects which road types or features can be used, estimated speed, and the traffic levels that are applied. + `Car`—Standard passenger vehicle routing using roads accessible to cars + `Pedestrian`—Walking routes using pedestrian paths, sidewalks, and crossings + `Scooter`—Light two-wheeled vehicle routing using roads and paths accessible to scooters + `Truck`—Commercial truck routing considering vehicle dimensions, weight restrictions, and hazardous material regulations The mode `Scooter` also applies to motorcycles; set this to `Scooter` when calculating isolines for motorcycles. Default value: `Car` Type: String Valid Values: `Car | Pedestrian | Scooter | Truck` Required: No ** [TravelModeOptions](#API_CalculateIsolines_RequestSyntax) ** Additional attributes that refine how reachable areas are calculated based on specific vehicle characteristics. These options help produce more accurate results by accounting for real-world constraints and capabilities. For example: + For trucks (`Truck`), specify dimensions, weight limits, and hazardous cargo restrictions to ensure isolines only include roads that can physically and legally accommodate the vehicle + For cars (`Car`), set maximum speed capabilities or indicate high-occupancy vehicle eligibility to better estimate reachable areas + For scooters (`Scooter`), specify engine type and speed limitations to more accurately model their travel capabilities Without these options, calculations use default assumptions that may not match your specific use case. Type: [IsolineTravelModeOptions](API_IsolineTravelModeOptions.md) object Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "ArrivalTime": "string", "DepartureTime": "string", "IsolineGeometryFormat": "string", "Isolines": [ { "Connections": [ { "FromPolygonIndex": number, "Geometry": { "LineString": [ [ number ] ], "Polyline": "string" }, "ToPolygonIndex": number } ], "DistanceThreshold": number, "Geometries": [ { "Polygon": [ [ [ number ] ] ], "PolylinePolygon": [ "string" ] } ], "TimeThreshold": number } ], "SnappedDestination": [ number ], "SnappedOrigin": [ number ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_CalculateIsolines_ResponseSyntax) ** The pricing bucket applied to this calculation. Different buckets apply based on the travel mode and thresholds used. The following data is returned in JSON format by the service. ** [ArrivalTime](#API_CalculateIsolines_ResponseSyntax) ** Time of arrival at the destination, used for traffic calculations. This attribute is returned only if the `Destination` and `ArrivalTime` attributes were provided in the request. 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])` ** [DepartureTime](#API_CalculateIsolines_ResponseSyntax) ** Time of departure from the origin, used for traffic calculations. This attribute is returned when `Origin` was provided in the request and either a specific departure time was requested (`DepartureTime`) or `DepartNow` was set to true. 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])` ** [IsolineGeometryFormat](#API_CalculateIsolines_ResponseSyntax) ** The format of the returned geometries, matching the format specified in the request. Either ` FlexiblePolyline` for compact encoding or `Simple` for GeoJSON-compatible coordinates. Default value:`FlexiblePolyline` Type: String Valid Values: `FlexiblePolyline | Simple` ** [Isolines](#API_CalculateIsolines_ResponseSyntax) ** Reachable areas, or isolines, for each threshold specified in the request. Type: Array of [Isoline](API_Isoline.md) objects Array Members: Minimum number of 1 item. Maximum number of 5 items. ** [SnappedDestination](#API_CalculateIsolines_ResponseSyntax) ** The actual point on the road network used for calculations, which may differ from the requested destination if `Destination` was not directly on a road. Type: Array of doubles Array Members: Fixed number of 2 items. ** [SnappedOrigin](#API_CalculateIsolines_ResponseSyntax) ** The actual point on the road network used for calculations, which may differ from the requested origin if `Origin` was not directly on a road. Type: Array of doubles Array Members: Fixed number of 2 items. ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** 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 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-routes-2020-11-19/CalculateIsolines) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-routes-2020-11-19/CalculateIsolines) # 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](https://docs.aws.amazon.com/location/latest/developerguide/calculate-route-matrix.html) 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](#API_CalculateRouteMatrix_RequestSyntax) ** 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](#API_CalculateRouteMatrix_RequestSyntax) ** Features that are allowed while calculating a route. Type: [RouteMatrixAllowOptions](API_RouteMatrixAllowOptions.md) object Required: No ** [Avoid](#API_CalculateRouteMatrix_RequestSyntax) ** 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](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only `TollRoads`, `Ferries`, and `ControlledAccessHighways`. Type: [RouteMatrixAvoidanceOptions](API_RouteMatrixAvoidanceOptions.md) object Required: No ** [DepartNow](#API_CalculateRouteMatrix_RequestSyntax) ** Uses the current time as the time of departure. Type: Boolean Required: No ** [DepartureTime](#API_CalculateRouteMatrix_RequestSyntax) ** 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](#API_CalculateRouteMatrix_RequestSyntax) ** List of destinations for the route. 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](https://docs.aws.amazon.com/location/latest/developerguide/routes-pricing.html) in the *Amazon Location Service Developer Guide*. Type: Array of [RouteMatrixDestination](API_RouteMatrixDestination.md) objects Array Members: Minimum number of 1 item. Required: Yes ** [Exclude](#API_CalculateRouteMatrix_RequestSyntax) ** Features to be strictly excluded while calculating the route. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteMatrixExclusionOptions](API_RouteMatrixExclusionOptions.md) object Required: No ** [OptimizeRoutingFor](#API_CalculateRouteMatrix_RequestSyntax) ** 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](#API_CalculateRouteMatrix_RequestSyntax) ** The position for the origin in World Geodetic System (WGS 84) format: [longitude, latitude]. 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](https://docs.aws.amazon.com/location/latest/developerguide/routes-pricing.html) in the *Amazon Location Service Developer Guide*. Type: Array of [RouteMatrixOrigin](API_RouteMatrixOrigin.md) objects Array Members: Minimum number of 1 item. Required: Yes ** [RoutingBoundary](#API_CalculateRouteMatrix_RequestSyntax) ** Boundary within which the matrix is to be calculated. All data, origins and destinations outside the boundary are considered invalid. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only `Unbounded` set to `true`. Default value: `Unbounded set to true` When request routing boundary was set as AutoCircle, the response routing boundary will return Circle derived from the AutoCircle settings. Type: [RouteMatrixBoundary](API_RouteMatrixBoundary.md) object Required: No ** [Traffic](#API_CalculateRouteMatrix_RequestSyntax) ** Traffic related options. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteMatrixTrafficOptions](API_RouteMatrixTrafficOptions.md) object Required: No ** [TravelMode](#API_CalculateRouteMatrix_RequestSyntax) ** Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) 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](#API_CalculateRouteMatrix_RequestSyntax) ** Travel mode related options for the provided travel mode. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteMatrixTravelModeOptions](API_RouteMatrixTravelModeOptions.md) 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](#API_CalculateRouteMatrix_ResponseSyntax) ** The pricing bucket for which the query is charged at. The following data is returned in JSON format by the service. ** [ErrorCount](#API_CalculateRouteMatrix_ResponseSyntax) ** 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](#API_CalculateRouteMatrix_ResponseSyntax) ** 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](API_RouteMatrixEntry.md) objects ** [RoutingBoundary](#API_CalculateRouteMatrix_ResponseSyntax) ** Boundary within which the matrix is to be calculated. All data, origins and destinations outside the boundary are considered invalid. When request routing boundary was set as AutoCircle, the response routing boundary will return Circle derived from the AutoCircle settings. Type: [RouteMatrixBoundary](API_RouteMatrixBoundary.md) object ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** 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 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-routes-2020-11-19/CalculateRouteMatrix) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-routes-2020-11-19/CalculateRouteMatrix) # CalculateRoutes `CalculateRoutes` computes routes given the following required parameters: `Origin` and `Destination`. For more information, see [Calculate routes](https://docs.aws.amazon.com/location/latest/developerguide/calculate-routes.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /routes?key=Key HTTP/1.1 Content-type: application/json { "Allow": { "Hot": boolean, "Hov": boolean }, "ArrivalTime": "string", "Avoid": { "Areas": [ { "Except": [ { "BoundingBox": [ number ], "Corridor": { "LineString": [ [ number ] ], "Radius": number }, "Polygon": [ [ [ number ] ] ], "PolylineCorridor": { "Polyline": "string", "Radius": number }, "PolylinePolygon": [ "string" ] } ], "Geometry": { "BoundingBox": [ number ], "Corridor": { "LineString": [ [ number ] ], "Radius": number }, "Polygon": [ [ [ number ] ] ], "PolylineCorridor": { "Polyline": "string", "Radius": number }, "PolylinePolygon": [ "string" ] } } ], "CarShuttleTrains": boolean, "ControlledAccessHighways": boolean, "DirtRoads": boolean, "Ferries": boolean, "SeasonalClosure": boolean, "TollRoads": boolean, "TollTransponders": boolean, "TruckRoadTypes": [ "string" ], "Tunnels": boolean, "UTurns": boolean, "ZoneCategories": [ { "Category": "string" } ] }, "DepartNow": boolean, "DepartureTime": "string", "Destination": [ number ], "DestinationOptions": { "AvoidActionsForDistance": number, "AvoidUTurns": boolean, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "SideOfStreet": { "Position": [ number ], "UseWith": "string" }, "StopDuration": number }, "Driver": { "Schedule": [ { "DriveDuration": number, "RestDuration": number } ] }, "Exclude": { "Countries": [ "string" ] }, "InstructionsMeasurementSystem": "string", "Languages": [ "string" ], "LegAdditionalFeatures": [ "string" ], "LegGeometryFormat": "string", "MaxAlternatives": number, "OptimizeRoutingFor": "string", "Origin": [ number ], "OriginOptions": { "AvoidActionsForDistance": number, "AvoidUTurns": boolean, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "SideOfStreet": { "Position": [ number ], "UseWith": "string" } }, "SpanAdditionalFeatures": [ "string" ], "Tolls": { "AllTransponders": boolean, "AllVignettes": boolean, "Currency": "string", "EmissionType": { "Co2EmissionClass": "string", "Type": "string" }, "VehicleCategory": "string" }, "Traffic": { "FlowEventThresholdOverride": number, "Usage": "string" }, "TravelMode": "string", "TravelModeOptions": { "Car": { "EngineType": "string", "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number }, "Pedestrian": { "Speed": number }, "Scooter": { "EngineType": "string", "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number }, "Truck": { "AxleCount": number, "EngineType": "string", "GrossWeight": number, "HazardousCargos": [ "string" ], "Height": number, "HeightAboveFirstAxle": number, "KpraLength": number, "Length": number, "LicensePlate": { "LastCharacter": "string" }, "MaxSpeed": number, "Occupancy": number, "PayloadCapacity": number, "TireCount": number, "Trailer": { "AxleCount": number, "TrailerCount": number }, "TruckType": "string", "TunnelRestrictionCode": "string", "WeightPerAxle": number, "WeightPerAxleGroup": { "Quad": number, "Quint": number, "Single": number, "Tandem": number, "Triple": number }, "Width": number } }, "TravelStepType": "string", "Waypoints": [ { "AvoidActionsForDistance": number, "AvoidUTurns": boolean, "Heading": number, "Matching": { "NameHint": "string", "OnRoadThreshold": number, "Radius": number, "Strategy": "string" }, "PassThrough": boolean, "Position": [ number ], "SideOfStreet": { "Position": [ number ], "UseWith": "string" }, "StopDuration": number } ] } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_CalculateRoutes_RequestSyntax) ** 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](#API_CalculateRoutes_RequestSyntax) ** Features that are allowed while calculating a route. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteAllowOptions](API_RouteAllowOptions.md) object Required: No ** [ArrivalTime](#API_CalculateRoutes_RequestSyntax) ** Time of arrival at the destination. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. 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 ** [Avoid](#API_CalculateRoutes_RequestSyntax) ** 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](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only `ControlledAccessHighways`, `Ferries`, and `TollRoads` Type: [RouteAvoidanceOptions](API_RouteAvoidanceOptions.md) object Required: No ** [DepartNow](#API_CalculateRoutes_RequestSyntax) ** Uses the current time as the time of departure. Type: Boolean Required: No ** [DepartureTime](#API_CalculateRoutes_RequestSyntax) ** 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 ** [Destination](#API_CalculateRoutes_RequestSyntax) ** The final position for the route. In the World Geodetic System (WGS 84) format: `[longitude, latitude]`. Type: Array of doubles Array Members: Fixed number of 2 items. Required: Yes ** [DestinationOptions](#API_CalculateRoutes_RequestSyntax) ** Destination related options. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteDestinationOptions](API_RouteDestinationOptions.md) object Required: No ** [Driver](#API_CalculateRoutes_RequestSyntax) ** Driver related options. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteDriverOptions](API_RouteDriverOptions.md) object Required: No ** [Exclude](#API_CalculateRoutes_RequestSyntax) ** Features to be strictly excluded while calculating the route. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteExclusionOptions](API_RouteExclusionOptions.md) object Required: No ** [InstructionsMeasurementSystem](#API_CalculateRoutes_RequestSyntax) ** Measurement system to be used for instructions within steps in the response. Type: String Valid Values: `Metric | Imperial` Required: No ** [Languages](#API_CalculateRoutes_RequestSyntax) ** List of languages for instructions within steps in the response. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Instructions in the requested language are returned only if they are available. Type: Array of strings Array Members: Minimum number of 0 items. Maximum number of 10 items. Length Constraints: Minimum length of 2. Maximum length of 35. Required: No ** [LegAdditionalFeatures](#API_CalculateRoutes_RequestSyntax) ** A list of optional additional parameters such as timezone that can be requested for each result. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only `PassThroughWaypoints`, `Summary`, and `TravelStepInstructions` + `Elevation`: Retrieves the elevation information for each location. + `Incidents`: Provides information on traffic incidents along the route. + `PassThroughWaypoints`: Indicates waypoints that are passed through without stopping. + `Summary`: Returns a summary of the route, including distance and duration. + `Tolls`: Supplies toll cost information along the route. + `TravelStepInstructions`: Provides step-by-step instructions for travel along the route. + `TruckRoadTypes`: Returns information about road types suitable for trucks. + `TypicalDuration`: Gives typical travel duration based on historical data. + `Zones`: Specifies the time zone information for each waypoint. Type: Array of strings Array Members: Minimum number of 0 items. Maximum number of 9 items. Valid Values: `Elevation | Incidents | PassThroughWaypoints | Summary | Tolls | TravelStepInstructions | TruckRoadTypes | TypicalDuration | Zones` Required: No ** [LegGeometryFormat](#API_CalculateRoutes_RequestSyntax) ** Specifies the format of the geometry returned for each leg of the route. You can choose between two different geometry encoding formats. `FlexiblePolyline`: A compact and precise encoding format for the leg geometry. For more information on the format, see the GitHub repository for [https://github.com/aws-geospatial/polyline](https://github.com/aws-geospatial/polyline). `Simple`: A less compact encoding, which is easier to decode but may be less precise and result in larger payloads. Type: String Valid Values: `FlexiblePolyline | Simple` Required: No ** [MaxAlternatives](#API_CalculateRoutes_RequestSyntax) ** Maximum number of alternative routes to be provided in the response, if available. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only up to 3 alternative routes. Type: Integer Valid Range: Minimum value of 0. Maximum value of 5. Required: No ** [OptimizeRoutingFor](#API_CalculateRoutes_RequestSyntax) ** Controls the trade-off between achieving the shortest travel time (`FastestRoute`) and achieving the shortest physical distance ((`ShortestRoute`) when calculating each route in the matrix. Default value: `FastestRoute` Type: String Valid Values: `FastestRoute | ShortestRoute` Required: No ** [Origin](#API_CalculateRoutes_RequestSyntax) ** The start position for the route in World Geodetic System (WGS 84) format: [longitude, latitude]. Type: Array of doubles Array Members: Fixed number of 2 items. Required: Yes ** [OriginOptions](#API_CalculateRoutes_RequestSyntax) ** Specifies how the origin point should be matched to the road network and any routing constraints that apply when the traveler is departing the origin. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteOriginOptions](API_RouteOriginOptions.md) object Required: No ** [SpanAdditionalFeatures](#API_CalculateRoutes_RequestSyntax) ** A list of optional features such as `SpeedLimit` that can be requested for a Span. A span is a section of a Leg for which the requested features have the same values. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of strings Array Members: Minimum number of 0 items. Maximum number of 24 items. Valid Values: `BestCaseDuration | CarAccess | Country | Distance | Duration | DynamicSpeed | FunctionalClassification | Gates | Incidents | Names | Notices | PedestrianAccess | RailwayCrossings | Region | RoadAttributes | RouteNumbers | ScooterAccess | SpeedLimit | TollSystems | TruckAccess | TruckRoadTypes | TypicalDuration | Zones | Consumption` Required: No ** [Tolls](#API_CalculateRoutes_RequestSyntax) ** Toll related options. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteTollOptions](API_RouteTollOptions.md) object Required: No ** [Traffic](#API_CalculateRoutes_RequestSyntax) ** Traffic related options. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: [RouteTrafficOptions](API_RouteTrafficOptions.md) object Required: No ** [TravelMode](#API_CalculateRoutes_RequestSyntax) ** Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only `Car`, `Pedestrian`, and `Scooter` values. Default value: `Car` Type: String Valid Values: `Car | Pedestrian | Scooter | Truck` Required: No ** [TravelModeOptions](#API_CalculateRoutes_RequestSyntax) ** Travel mode related options for the provided travel mode. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions support only `Car` and `Pedestrian` travel mode options. Type: [RouteTravelModeOptions](API_RouteTravelModeOptions.md) object Required: No ** [TravelStepType](#API_CalculateRoutes_RequestSyntax) ** Type of step returned by the response. `Default` provides basic steps intended for web based applications. `TurnByTurn` provides detailed instructions with more granularity intended for a turn based navigation system. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions `Default` does not return any steps. Type: String Valid Values: `Default | TurnByTurn` Required: No ** [Waypoints](#API_CalculateRoutes_RequestSyntax) ** List of waypoints between the Origin and Destination. For [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers, `ap-southeast-1` and `ap-southeast-5` regions max length is `100`. Max length: `23` Type: Array of [RouteWaypoint](API_RouteWaypoint.md) objects Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "LegGeometryFormat": "string", "Notices": [ { "Code": "string", "Impact": "string" } ], "Routes": [ { "Legs": [ { "FerryLegDetails": { "AfterTravelSteps": [ { "Duration": number, "Instruction": "string", "Type": "string" } ], "Arrival": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number }, "Time": "string" }, "BeforeTravelSteps": [ { "Duration": number, "Instruction": "string", "Type": "string" } ], "Departure": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number }, "Time": "string" }, "Notices": [ { "Code": "string", "Impact": "string" } ], "PassThroughWaypoints": [ { "GeometryOffset": number, "Place": { "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number } } ], "RouteName": "string", "Spans": [ { "Country": "string", "Distance": number, "Duration": number, "GeometryOffset": number, "Names": [ { "Language": "string", "Value": "string" } ], "Region": "string" } ], "Summary": { "Overview": { "Distance": number, "Duration": number }, "TravelOnly": { "Duration": number } }, "TravelSteps": [ { "Distance": number, "Duration": number, "GeometryOffset": number, "Instruction": "string", "Type": "string" } ] }, "Geometry": { "LineString": [ [ number ] ], "Polyline": "string" }, "Language": "string", "PedestrianLegDetails": { "Arrival": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Departure": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Notices": [ { "Code": "string", "Impact": "string" } ], "PassThroughWaypoints": [ { "GeometryOffset": number, "Place": { "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number } } ], "Spans": [ { "BestCaseDuration": number, "Country": "string", "Distance": number, "Duration": number, "DynamicSpeed": { "BestCaseSpeed": number, "TurnDuration": number, "TypicalSpeed": number }, "FunctionalClassification": number, "GeometryOffset": number, "Incidents": [ number ], "Names": [ { "Language": "string", "Value": "string" } ], "PedestrianAccess": [ "string" ], "Region": "string", "RoadAttributes": [ "string" ], "RouteNumbers": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "SpeedLimit": { "MaxSpeed": number, "Unlimited": boolean }, "TypicalDuration": number } ], "Summary": { "Overview": { "Distance": number, "Duration": number }, "TravelOnly": { "Duration": number } }, "TravelSteps": [ { "ContinueStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ] }, "CurrentRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "Distance": number, "Duration": number, "ExitNumber": [ { "Language": "string", "Value": "string" } ], "GeometryOffset": number, "Instruction": "string", "KeepStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "NextRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "RoundaboutEnterStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "RoundaboutExitStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "RelativeExit": number, "RoundaboutAngle": number, "SteeringDirection": "string" }, "RoundaboutPassStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Signpost": { "Labels": [ { "RouteNumber": { "Direction": "string", "Language": "string", "Value": "string" }, "Text": { "Language": "string", "Value": "string" } } ] }, "TurnStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Type": "string" } ] }, "TravelMode": "string", "Type": "string", "VehicleLegDetails": { "Arrival": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Departure": { "Place": { "Name": "string", "OriginalPosition": [ number ], "Position": [ number ], "SideOfStreet": "string", "WaypointIndex": number }, "Time": "string" }, "Incidents": [ { "Description": "string", "EndTime": "string", "Severity": "string", "StartTime": "string", "Type": "string" } ], "Notices": [ { "Code": "string", "Details": [ { "Title": "string", "ViolatedConstraints": { "AllHazardsRestricted": boolean, "AxleCount": { "Max": number, "Min": number }, "HazardousCargos": [ "string" ], "MaxHeight": number, "MaxKpraLength": number, "MaxLength": number, "MaxPayloadCapacity": number, "MaxWeight": { "Type": "string", "Value": number }, "MaxWeightPerAxle": number, "MaxWeightPerAxleGroup": { "Quad": number, "Quint": number, "Single": number, "Tandem": number, "Triple": number }, "MaxWidth": number, "Occupancy": { "Max": number, "Min": number }, "RestrictedTimes": "string", "TimeDependent": boolean, "TrailerCount": { "Max": number, "Min": number }, "TravelMode": boolean, "TruckRoadType": "string", "TruckType": "string", "TunnelRestrictionCode": "string" } } ], "Impact": "string" } ], "PassThroughWaypoints": [ { "GeometryOffset": number, "Place": { "OriginalPosition": [ number ], "Position": [ number ], "WaypointIndex": number } } ], "Spans": [ { "BestCaseDuration": number, "CarAccess": [ "string" ], "Country": "string", "Distance": number, "Duration": number, "DynamicSpeed": { "BestCaseSpeed": number, "TurnDuration": number, "TypicalSpeed": number }, "FunctionalClassification": number, "Gate": "string", "GeometryOffset": number, "Incidents": [ number ], "Names": [ { "Language": "string", "Value": "string" } ], "Notices": [ number ], "RailwayCrossing": "string", "Region": "string", "RoadAttributes": [ "string" ], "RouteNumbers": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "ScooterAccess": [ "string" ], "SpeedLimit": { "MaxSpeed": number, "Unlimited": boolean }, "TollSystems": [ number ], "TruckAccess": [ "string" ], "TruckRoadTypes": [ number ], "TypicalDuration": number, "Zones": [ number ] } ], "Summary": { "Overview": { "BestCaseDuration": number, "Distance": number, "Duration": number, "TypicalDuration": number }, "TravelOnly": { "BestCaseDuration": number, "Duration": number, "TypicalDuration": number } }, "Tolls": [ { "Country": "string", "PaymentSites": [ { "Name": "string", "Position": [ number ] } ], "Rates": [ { "ApplicableTimes": "string", "ConvertedPrice": { "Currency": "string", "Estimate": boolean, "PerDuration": number, "Range": boolean, "RangeValue": { "Max": number, "Min": number }, "Value": number }, "Id": "string", "LocalPrice": { "Currency": "string", "Estimate": boolean, "PerDuration": number, "Range": boolean, "RangeValue": { "Max": number, "Min": number }, "Value": number }, "Name": "string", "Pass": { "IncludesReturnTrip": boolean, "SeniorPass": boolean, "TransferCount": number, "TripCount": number, "ValidityPeriod": { "Period": "string", "PeriodCount": number } }, "PaymentMethods": [ "string" ], "Transponders": [ { "SystemName": "string" } ] } ], "Systems": [ number ] } ], "TollSystems": [ { "Name": "string" } ], "TravelSteps": [ { "ContinueHighwayStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "ContinueStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ] }, "CurrentRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "Distance": number, "Duration": number, "EnterHighwayStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "ExitNumber": [ { "Language": "string", "Value": "string" } ], "ExitStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "RelativeExit": number, "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "GeometryOffset": number, "Instruction": "string", "KeepStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "NextRoad": { "RoadName": [ { "Language": "string", "Value": "string" } ], "RouteNumber": [ { "Direction": "string", "Language": "string", "Value": "string" } ], "Towards": [ { "Language": "string", "Value": "string" } ], "Type": "string" }, "RampStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "RoundaboutEnterStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "RoundaboutExitStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "RelativeExit": number, "RoundaboutAngle": number, "SteeringDirection": "string" }, "RoundaboutPassStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Signpost": { "Labels": [ { "RouteNumber": { "Direction": "string", "Language": "string", "Value": "string" }, "Text": { "Language": "string", "Value": "string" } } ] }, "TurnStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" }, "Type": "string", "UTurnStepDetails": { "Intersection": [ { "Language": "string", "Value": "string" } ], "SteeringDirection": "string", "TurnAngle": number, "TurnIntensity": "string" } } ], "TruckRoadTypes": [ "string" ], "Zones": [ { "Category": "string", "Name": "string" } ] } } ], "MajorRoadLabels": [ { "RoadName": { "Language": "string", "Value": "string" }, "RouteNumber": { "Direction": "string", "Language": "string", "Value": "string" } } ], "Summary": { "Distance": number, "Duration": number, "Tolls": { "Total": { "Currency": "string", "Estimate": boolean, "Range": boolean, "RangeValue": { "Max": number, "Min": number }, "Value": number } } } } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_CalculateRoutes_ResponseSyntax) ** The pricing bucket for which the query is charged at. The following data is returned in JSON format by the service. ** [LegGeometryFormat](#API_CalculateRoutes_ResponseSyntax) ** Specifies the format of the geometry returned for each leg of the route. Type: String Valid Values: `FlexiblePolyline | Simple` ** [Notices](#API_CalculateRoutes_ResponseSyntax) ** Notices are additional information returned that indicate issues that occurred during route calculation. Not supported in `ap-southeast-1` and `ap-southeast-5` regions for [GrabMaps](https://docs.aws.amazon.com/location/latest/developerguide/GrabMaps.html) customers. Type: Array of [RouteResponseNotice](API_RouteResponseNotice.md) objects ** [Routes](#API_CalculateRoutes_ResponseSyntax) ** The path from the origin to the destination. Type: Array of [Route](API_Route.md) objects ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** 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 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-routes-2020-11-19/CalculateRoutes) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-routes-2020-11-19/CalculateRoutes) # OptimizeWaypoints `OptimizeWaypoints` calculates the optimal order to travel between a set of waypoints to minimize either the travel time or the distance travelled during the journey, based on road network restrictions and the traffic pattern data. For more information, see [Optimize waypoints](https://docs.aws.amazon.com/location/latest/developerguide/actions-optimize-waypoints.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /optimize-waypoints?key=Key HTTP/1.1 Content-type: application/json { "Avoid": { "Areas": [ { "Geometry": { "BoundingBox": [ number ] } } ], "CarShuttleTrains": boolean, "ControlledAccessHighways": boolean, "DirtRoads": boolean, "Ferries": boolean, "TollRoads": boolean, "Tunnels": boolean, "UTurns": boolean }, "Clustering": { "Algorithm": "string", "DrivingDistanceOptions": { "DrivingDistance": number } }, "DepartureTime": "string", "Destination": [ number ], "DestinationOptions": { "AccessHours": { "From": { "DayOfWeek": "string", "TimeOfDay": "string" }, "To": { "DayOfWeek": "string", "TimeOfDay": "string" } }, "AppointmentTime": "string", "Heading": number, "Id": "string", "ServiceDuration": number, "SideOfStreet": { "Position": [ number ], "UseWith": "string" } }, "Driver": { "RestCycles": { "LongCycle": { "RestDuration": number, "WorkDuration": number }, "ShortCycle": { "RestDuration": number, "WorkDuration": number } }, "RestProfile": { "Profile": "string" }, "TreatServiceTimeAs": "string" }, "Exclude": { "Countries": [ "string" ] }, "OptimizeSequencingFor": "string", "Origin": [ number ], "OriginOptions": { "Id": "string" }, "Traffic": { "Usage": "string" }, "TravelMode": "string", "TravelModeOptions": { "Pedestrian": { "Speed": number }, "Truck": { "GrossWeight": number, "HazardousCargos": [ "string" ], "Height": number, "Length": number, "Trailer": { "TrailerCount": number }, "TruckType": "string", "TunnelRestrictionCode": "string", "WeightPerAxle": number, "Width": number } }, "Waypoints": [ { "AccessHours": { "From": { "DayOfWeek": "string", "TimeOfDay": "string" }, "To": { "DayOfWeek": "string", "TimeOfDay": "string" } }, "AppointmentTime": "string", "Before": [ number ], "Heading": number, "Id": "string", "Position": [ number ], "ServiceDuration": number, "SideOfStreet": { "Position": [ number ], "UseWith": "string" } } ] } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_OptimizeWaypoints_RequestSyntax) ** 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. ** [Avoid](#API_OptimizeWaypoints_RequestSyntax) ** Features that are avoided. Avoidance is on a best-case basis. If an avoidance can't be satisfied for a particular case, this setting is ignored. Type: [WaypointOptimizationAvoidanceOptions](API_WaypointOptimizationAvoidanceOptions.md) object Required: No ** [Clustering](#API_OptimizeWaypoints_RequestSyntax) ** Clustering allows you to specify how nearby waypoints can be clustered to improve the optimized sequence. Type: [WaypointOptimizationClusteringOptions](API_WaypointOptimizationClusteringOptions.md) object Required: No ** [DepartureTime](#API_OptimizeWaypoints_RequestSyntax) ** Departure time from the waypoint. 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 ** [Destination](#API_OptimizeWaypoints_RequestSyntax) ** The final position for the route in the World Geodetic System (WGS 84) format: `[longitude, latitude]`. Type: Array of doubles Array Members: Fixed number of 2 items. Required: No ** [DestinationOptions](#API_OptimizeWaypoints_RequestSyntax) ** Destination related options. Type: [WaypointOptimizationDestinationOptions](API_WaypointOptimizationDestinationOptions.md) object Required: No ** [Driver](#API_OptimizeWaypoints_RequestSyntax) ** Driver related options. Type: [WaypointOptimizationDriverOptions](API_WaypointOptimizationDriverOptions.md) object Required: No ** [Exclude](#API_OptimizeWaypoints_RequestSyntax) ** Features to be strictly excluded while calculating the route. Type: [WaypointOptimizationExclusionOptions](API_WaypointOptimizationExclusionOptions.md) object Required: No ** [OptimizeSequencingFor](#API_OptimizeWaypoints_RequestSyntax) ** Specifies the optimization criteria for the calculated sequence. Default value: `FastestRoute`. Type: String Valid Values: `FastestRoute | ShortestRoute` Required: No ** [Origin](#API_OptimizeWaypoints_RequestSyntax) ** The start position for the route in World Geodetic System (WGS 84) format: [longitude, latitude]. Type: Array of doubles Array Members: Fixed number of 2 items. Required: Yes ** [OriginOptions](#API_OptimizeWaypoints_RequestSyntax) ** Origin related options. Type: [WaypointOptimizationOriginOptions](API_WaypointOptimizationOriginOptions.md) object Required: No ** [Traffic](#API_OptimizeWaypoints_RequestSyntax) ** Traffic-related options. Type: [WaypointOptimizationTrafficOptions](API_WaypointOptimizationTrafficOptions.md) object Required: No ** [TravelMode](#API_OptimizeWaypoints_RequestSyntax) ** 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](#API_OptimizeWaypoints_RequestSyntax) ** Travel mode related options for the provided travel mode. Type: [WaypointOptimizationTravelModeOptions](API_WaypointOptimizationTravelModeOptions.md) object Required: No ** [Waypoints](#API_OptimizeWaypoints_RequestSyntax) ** List of waypoints between the `Origin` and `Destination`. Type: Array of [WaypointOptimizationWaypoint](API_WaypointOptimizationWaypoint.md) objects Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "Connections": [ { "Distance": number, "From": "string", "RestDuration": number, "To": "string", "TravelDuration": number, "WaitDuration": number } ], "Distance": number, "Duration": number, "ImpedingWaypoints": [ { "FailedConstraints": [ { "Constraint": "string", "Reason": "string" } ], "Id": "string", "Position": [ number ] } ], "OptimizedWaypoints": [ { "ArrivalTime": "string", "ClusterIndex": number, "DepartureTime": "string", "Id": "string", "Position": [ number ] } ], "TimeBreakdown": { "RestDuration": number, "ServiceDuration": number, "TravelDuration": number, "WaitDuration": number } } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_OptimizeWaypoints_ResponseSyntax) ** The pricing bucket for which the query is charged at. The following data is returned in JSON format by the service. ** [Connections](#API_OptimizeWaypoints_ResponseSyntax) ** Details about the connection from one waypoint to the next, within the optimized sequence. Type: Array of [WaypointOptimizationConnection](API_WaypointOptimizationConnection.md) objects ** [Distance](#API_OptimizeWaypoints_ResponseSyntax) ** Overall distance to travel the whole sequence. Type: Long Valid Range: Minimum value of 0. Maximum value of 4294967295. ** [Duration](#API_OptimizeWaypoints_ResponseSyntax) ** Overall duration to travel the whole sequence. **Unit**: `seconds` Type: Long Valid Range: Minimum value of 0. Maximum value of 4294967295. ** [ImpedingWaypoints](#API_OptimizeWaypoints_ResponseSyntax) ** Returns waypoints that caused the optimization problem to fail, and the constraints that were unsatisfied leading to the failure. Type: Array of [WaypointOptimizationImpedingWaypoint](API_WaypointOptimizationImpedingWaypoint.md) objects ** [OptimizedWaypoints](#API_OptimizeWaypoints_ResponseSyntax) ** Waypoints in the order of the optimized sequence. Type: Array of [WaypointOptimizationOptimizedWaypoint](API_WaypointOptimizationOptimizedWaypoint.md) objects ** [TimeBreakdown](#API_OptimizeWaypoints_ResponseSyntax) ** Time breakdown for the sequence. Type: [WaypointOptimizationTimeBreakdown](API_WaypointOptimizationTimeBreakdown.md) object ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** 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 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-routes-2020-11-19/OptimizeWaypoints) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-routes-2020-11-19/OptimizeWaypoints) # SnapToRoads `SnapToRoads` matches GPS trace to roads most likely traveled on. For more information, see [Snap to Roads](https://docs.aws.amazon.com/location/latest/developerguide/snap-to-roads.html) in the *Amazon Location Service Developer Guide*. ## Request Syntax ``` POST /snap-to-roads?key=Key HTTP/1.1 Content-type: application/json { "SnappedGeometryFormat": "string", "SnapRadius": number, "TracePoints": [ { "Heading": number, "Position": [ number ], "Speed": number, "Timestamp": "string" } ], "TravelMode": "string", "TravelModeOptions": { "Truck": { "GrossWeight": number, "HazardousCargos": [ "string" ], "Height": number, "Length": number, "Trailer": { "TrailerCount": number }, "TunnelRestrictionCode": "string", "Width": number } } } ``` ## URI Request Parameters The request uses the following URI parameters. ** [Key](#API_SnapToRoads_RequestSyntax) ** 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. ** [SnappedGeometryFormat](#API_SnapToRoads_RequestSyntax) ** Chooses what the returned SnappedGeometry format should be. Default value: `FlexiblePolyline` Type: String Valid Values: `FlexiblePolyline | Simple` Required: No ** [SnapRadius](#API_SnapToRoads_RequestSyntax) ** The radius around the provided tracepoint that is considered for snapping. **Unit**: `meters` Default value: `300` Type: Long Valid Range: Minimum value of 0. Maximum value of 10000. Required: No ** [TracePoints](#API_SnapToRoads_RequestSyntax) ** List of trace points to be snapped onto the road network. Type: Array of [RoadSnapTracePoint](API_RoadSnapTracePoint.md) objects Array Members: Minimum number of 2 items. Maximum number of 5000 items. Required: Yes ** [TravelMode](#API_SnapToRoads_RequestSyntax) ** 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](#API_SnapToRoads_RequestSyntax) ** Travel mode related options for the provided travel mode. Type: [RoadSnapTravelModeOptions](API_RoadSnapTravelModeOptions.md) object Required: No ## Response Syntax ``` HTTP/1.1 200 x-amz-geo-pricing-bucket: PricingBucket Content-type: application/json { "Notices": [ { "Code": "string", "Title": "string", "TracePointIndexes": [ number ] } ], "SnappedGeometry": { "LineString": [ [ number ] ], "Polyline": "string" }, "SnappedGeometryFormat": "string", "SnappedTracePoints": [ { "Confidence": number, "OriginalPosition": [ number ], "SnappedPosition": [ number ] } ] } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ** [PricingBucket](#API_SnapToRoads_ResponseSyntax) ** The pricing bucket for which the query is charged at. The following data is returned in JSON format by the service. ** [Notices](#API_SnapToRoads_ResponseSyntax) ** Notices are additional information returned that indicate issues that occurred during route calculation. Type: Array of [RoadSnapNotice](API_RoadSnapNotice.md) objects ** [SnappedGeometry](#API_SnapToRoads_ResponseSyntax) ** The interpolated geometry for the snapped route onto the road network. Type: [RoadSnapSnappedGeometry](API_RoadSnapSnappedGeometry.md) object ** [SnappedGeometryFormat](#API_SnapToRoads_ResponseSyntax) ** Specifies the format of the geometry returned for each leg of the route. Type: String Valid Values: `FlexiblePolyline | Simple` ** [SnappedTracePoints](#API_SnapToRoads_ResponseSyntax) ** The trace points snapped onto the road network. Type: Array of [RoadSnapSnappedTracePoint](API_RoadSnapSnappedTracePoint.md) objects ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** 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 ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/geo-routes-2020-11-19/SnapToRoads) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/geo-routes-2020-11-19/SnapToRoads)