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

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

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

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 object

Required: No

ArrivalTime

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

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 object

Required: No

DepartNow

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

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

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

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 object

Required: No

IsolineGeometryFormat

The format of the returned IsolineGeometry.

Default value:FlexiblePolyline

Type: String

Valid Values: FlexiblePolyline | Simple

Required: No

IsolineGranularity

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 object

Required: No

OptimizeIsolineFor

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

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

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

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 object

Required: No

Thresholds

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 in the Amazon Location Service Developer Guide.

Type: IsolineThresholds object

Required: Yes

Traffic

Configures how real-time and historical traffic data affects isoline calculations. Traffic patterns can significantly impact reachable areas, especially during peak hours.

Type: IsolineTrafficOptions object

Required: No

TravelMode

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

Note

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

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

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

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

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

Reachable areas, or isolines, for each threshold specified in the request.

Type: Array of Isoline objects

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

SnappedDestination

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

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

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

HTTP Status Code: 400