search icon
TravelTime API
Overview
Developer Tools
Database Plugins
TravelTime API
SDK
TravelTime API
Isochrone API
JSON
Distance Map API
TravelTime API
Travel Time Matrix API
JSON
Travel Time Matrix API
Protocol Buffers
TravelTime API
Routes API
JSON
Geocoding API
Additional API Reference
Error Handling
TravelTime API
ArcGIS plugin
QGIS plugin
Alteryx plugin
TravelTime.comchevronDocs

Isochronesanchor icon

Getting a TravelTime API keyanchor icon

  • If you don’t already have a TravelTime API key, then you can get a free key by creating an account here
  • Once you’ve verified your email and logged in, you’ll land on your new TravelTime account dashboard
  • Here you can find your API credentials that you will need to use when making any requests to the TravelTime API
TravelTime API application

Making a Requestanchor icon

  • Generating an Isochrone requires a single POST request
  • The required parameters are:
    • ID - a unique identifier for the isochrone used as a reference in the subsequent API response
    • Latitude and longitude coordinates - these set the departure or arrival location
    • Transportation type - the most popular are ‘driving’, ‘public_transport’, ‘walking’, and ‘cycling’, but a full list can be found here
    • Departure or Arrival time - this must be in extended ISO-8601 format, for example 2021-09-27T08:00:00Z
    • Travel time - the maximum journey time in seconds
  • As a simple JSON request body, this looks like the following example:

Isochrone Request

{
  "departure_searches": [
    {
      "id": "My first isochrone",
      "coords": {
        "lat": 51.507609,
        "lng": -0.128315
      },
      "departure_time": "2021-09-27T08:00:00Z",
      "travel_time": 3600,
      "transportation": {
        "type": "driving"
      }
    }
  ]
}
  • To make the request, copy the following Curl request

Curl request

curl -X POST https://api.traveltimeapp.com/v4/time-map \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Application-Id: YOUR_APP_ID' \
-H 'X-Api-Key: YOUR_APP_KEY' \
-d '{
"departure_searches": [
  {
    "id": "My first isochrone",
    "coords": {
      "lat": 51.507609,
      "lng": -0.128315
    },
    "departure_time": "2021-09-27T08:00:00Z",
    "travel_time": 3600,
    "transportation": {
      "type": "driving"
    }
  }
]}'

Note: you’ll need to enter your own Application ID and API Key in place of the placeholders

  • A full list of available parameters, including optional ones, can be found here

Interpreting the Responseanchor icon

Successful requestsanchor icon

  • A successful request will return a response that includes:
    • The ID of the search
    • ‘Shells’ - these are the areas covered by the isochrone
    • ‘Holes’ - these are areas within specific shells that are not covered by the isochrone

{
  "results": [
    {
      "search_id": "My first isochrone",
      "shapes": [
        {
          "shell": [
            {
              "lat": 51.48696930248525,
              "lng": -0.31584515200982954
            },
            {
              "lat": 51.48696930248525,
              "lng": -0.31630523234778996
            },
            ...
            {
              "lat": 51.48696930248525,
              "lng": -0.31584515200982954
            }
          ],
          "holes": []
        },
        {
          "shell": [
            {
              "lat": 51.465109890241166,
              "lng": -0.3025028222089773
            },
            {
              "lat": 51.46525370216383,
              "lng": -0.3027328623779575
            },
            ...
            {
              "lat": 51.465109890241166,
              "lng": -0.3020427418710169
            },
            {
              "lat": 51.465109890241166,
              "lng": -0.3025028222089773
            }
          ],
          "holes": []
        },
        {
          "shell": [
            {
              "lat": 51.465109890241166,
              "lng": -0.2472931816537267
            },
            {
              "lat": 51.46525370216383,
              "lng": -0.24752322182270692
            },
            ...
            {
              "lat": 51.465109890241166,
              "lng": -0.2472931816537267
            }
          ],
          "holes": []
        }
      ],
      "properties": {}
    }
  ]
}
  • Note that the returned isochrone is often a multi-polygon, with multiple unconnected Shells

Unsuccessful requestsanchor icon

  • An unsuccessful request will return an error message
  • For example, if invalid API credentials are used, the following error is returned

{
  "http_status": 401,
  "error_code": 10,
  "description": "Application Id or Api Key is invalid",
  "documentation_link": "http://docs.traveltimeplatform.com/reference/error-codes",
  "additional_info": {}
}
  • A full list of error codes can be found here