Travel Time Matrix

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

The simplest way to create a Distance Matrix is using the Time Filter endpoint
Generating a Distance Matrix requires a single POST request
The required parameters are:
- IDs - unique identifiers for the departure and arrival locations
- Latitude and longitude coordinates - these set the departure and arrival locations
- 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 (any journeys beyond this will be returned as Unreachable)
- Properties- the desired properties to be returned for each journey, where the options are route, travel_time, distance, fares
As a simple JSON request body, this looks like the following example:

{
  "locations": [
    {
      "id": "TravelTime HQ",
      "coords": {
        "lat": 51.51198245486377,
        "lng": -0.1278277598563
      }
    },
    {
      "id": "Hyde Park",
      "coords": {
        "lat": 51.503120589264064,
        "lng": -0.15282095066100
      }
    },
    {
      "id": "London Eye",
      "coords": {
        "lat": 51.503341807681544,
        "lng": -0.11952824596429
      }
    },
    {
      "id": "Houses of Parliament",
      "coords": {
        "lat": 51.499580735687275,
        "lng": -0.12479520475271223
      }
    },
    {
      "id": "Wimbledon Tennis Club",
      "coords": {
        "lat": 51.43540206193277,
        "lng": -0.2140336019409371
      }
    }
  ],
  "departure_searches": [
    {
      "id": "One-to-many Matrix",
      "departure_location_id": "TravelTime HQ",
      "arrival_location_ids": [
        "Hyde Park",
        "London Eye",
        "Houses of Parliament",
        "Wimbledon Tennis Club"
      ],
      "departure_time": "2021-09-21T08:00:00Z",
      "travel_time": 3600,
      "properties": [
        "travel_time",
        "distance"
      ],
      "transportation": {
        "type": "driving"
      }
    }
  ]
}

To make the request, copy the following Curl request

curl -X POST https://api.traveltimeapp.com/v4/time-filter \
-H 'Content-Type: application/json' \
-H 'X-Application-Id: YOUR_APP_ID' \
-H 'X-Api-Key: YOUR_APP_KEY' \
-d '{
  "locations": [
    {
      "id": "TravelTime HQ",
      "coords": {
        "lat": 51.51198245486377,
        "lng": -0.1278277598563
      }
    },
    {
      "id": "Hyde Park",
      "coords": {
        "lat": 51.503120589264064,
        "lng": -0.15282095066100
      }
    },
    {
      "id": "London Eye",
      "coords": {
        "lat": 51.503341807681544,
        "lng": -0.11952824596429
      }
    },
    {
      "id": "Houses of Parliament",
      "coords": {
        "lat": 51.499580735687275,
        "lng": -0.12479520475271223
      }
    },
    {
      "id": "Wimbledon Tennis Club",
      "coords": {
        "lat": 51.43540206193277,
        "lng": -0.2140336019409371
      }
    }
  ],
  "departure_searches": [
    {
      "id": "One-to-many Matrix",
      "departure_location_id": "TravelTime HQ",
      "arrival_location_ids": [
        "Hyde Park",
        "London Eye",
        "Houses of Parliament",
        "Wimbledon Tennis Club"
      ],
      "departure_time": "2021-09-21T08:00:00Z",
      "travel_time": 3600,
      "properties": [
        "travel_time",
        "distance"
      ],
      "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
- The ID of each location within the search
- The requested Properties for each location - the travel_time unit is seconds, the distance unit is metres
- Any Unreachable locations - no Properties will be returned for these locations

{
  "results": [
    {
      "search_id": "One-to-many Matrix",
      "locations": [
        {
          "id": "London Eye",
          "properties": [
            {
              "travel_time": 670,
              "distance": 2504
            }
          ]
        },
        {
          "id": "Wimbledon Tennis Club",
          "properties": [
            {
              "travel_time": 3229,
              "distance": 14008
            }
          ]
        },
        {
          "id": "Hyde Park",
          "properties": [
            {
              "travel_time": 1037,
              "distance": 3426
            }
          ]
        },
        {
          "id": "Houses of Parliament",
          "properties": [
            {
              "travel_time": 785,
              "distance": 1802
            }
          ]
        }
      ],
      "unreachable": [

      ]
    }
  ]
}

To calculate a matrix with multiple origins and multiple destinations, simply add multiple Searches into the request. Each of these Searches can then include up to 2,000 Locations

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

Alternative Distance Matrix endpoints

If you are looking to create much larger Distance Matrices, or require even lower response times, there are two alternative endpoints you can use:

Time Filter Fast (JSON) - a stripped down version of the Time Filter (JSON) endpoint that allows up to 100,000 locations per request
Time Filter Fast (Protobuf) - our highest performance endpoint allowing up to 200,000 elements per request in under 150ms