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

CalculateIsolines

Use the CalculateIsolines action to find service areas that can be reached in a given threshold of time, distance.

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

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 an isoline.

Type: IsolineAllowOptions object

Required: No

ArrivalTime

Time of arrival at the destination.

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

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: IsolineAvoidanceOptions 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

Destination

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

Destination related options.

Type: IsolineDestinationOptions object

Required: No

IsolineGeometryFormat

The format of the returned IsolineGeometry.

Default Value:FlexiblePolyline

Type: String

Valid Values: FlexiblePolyline | Simple

Required: No

IsolineGranularity

Defines the granularity of the returned Isoline.

Type: IsolineGranularityOptions object

Required: No

OptimizeIsolineFor

Specifies the optimization criteria for when calculating an isoline. AccurateCalculation generates an isoline of higher granularity that is more precise. FastCalculation generates an isoline faster by reducing the granularity, and in turn the quality of the isoline. BalancedCalculation generates an isoline by balancing between quality and performance.

Default Value: BalancedCalculation

Type: String

Valid Values: AccurateCalculation | BalancedCalculation | FastCalculation

Required: No

OptimizeRoutingFor

Specifies the optimization criteria for calculating a route.

Default Value: FastestRoute

Type: String

Valid Values: FastestRoute | ShortestRoute

Required: No

Origin

The start position for the route.

Type: Array of doubles

Array Members: Fixed number of 2 items.

Required: No

OriginOptions

Origin related options.

Type: IsolineOriginOptions object

Required: No

Thresholds

Threshold to be used for the isoline calculation. Up to 3 thresholds per provided type can be requested.

Type: IsolineThresholds object

Required: Yes

Traffic

Traffic related options.

Type: IsolineTrafficOptions object

Required: No

TravelMode

Specifies the mode of transport when calculating a route. Used in estimating the speed of travel and road compatibility.

Note

The mode Scooter also applies to motorcycles, set to Scooter when wanted to calculate options for motorcycles.

Default Value: Car

Type: String

Valid Values: Car | Pedestrian | Scooter | Truck

Required: No

TravelModeOptions

Travel mode related options for the provided travel mode.

Type: IsolineTravelModeOptions 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: The pricing bucket for which the query is charged at.

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

ArrivalTime

Time of arrival at the destination. This parameter is returned only if the Destination parameters was 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

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])

IsolineGeometryFormat

The format of the returned IsolineGeometry.

Default Value:FlexiblePolyline

Type: String

Valid Values: FlexiblePolyline | Simple

Isolines

Calculated isolines and associated properties.

Type: Array of Isoline objects

Array Members: Minimum number of 1 item. Maximum number of 5 items.

SnappedDestination

Snapped destination that was used for the Isoline calculation.

Type: Array of doubles

Array Members: Fixed number of 2 items.

SnappedOrigin

Snapped origin that was used for the Isoline calculation.

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 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