Isochrones

Getting a TravelTime API key

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

Making a Request

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 Response

Successful requests

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 requests

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