TravelTime Docs logo
TravelTime API
ArcGIS plugin
QGIS plugin
Alteryx plugin

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
      },
      "transportation": {
        "type": "driving"
      },
      "departure_time": "2021-09-27T08:00:00Z",
      "travel_time": 3600
    }
  ]
}
  • 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/geo+json' \
  -H 'X-Application-Id: XXXXXXXX' \
  -H'X-Api-Key: XXXXXXXX' \
  -d '{
  "departure_searches": [
    {
      "id": "GeoJSON_Test",
      "coords": {
        "lat": 51.507609, 
        "lng": -0.128315
      },
      "transportation": {
        "type": "driving"
      },
      "departure_time": "2021-10-01T08:00:00Z",
      "travel_time": 3600
      }
  ]}'

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