TravelTime Docs logo
TravelTime API
Overview
Developer Tools
Database Plugins
TravelTime API
SDK
TravelTime API
Isochrone API
JSON
Travel Time Matrix API
JSON
Travel Time Matrix API
Protocol Buffers
Routes API
Geocoding API
Additional API Reference
Error Handling
TravelTime API
ArcGIS plugin
QGIS plugin
Alteryx plugin

Travel Time Matrixanchor 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

  • 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_API_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 Responseanchor icon

Successful requestsanchor icon

  • 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": 1004,
              "distance": 2337
            }
          ]
        },
        {
          "id": "Hyde Park",
          "properties": [
            {
              "travel_time": 1324,
              "distance": 3172
            }
          ]
        },
        {
          "id": "Houses of Parliament",
          "properties": [
            {
              "travel_time": 904,
              "distance": 1775
            }
          ]
        }
      ],
      "unreachable": [
        "Wimbledon Tennis Club"
      ]
    }
  ]
}
  • 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 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

Alternative Distance Matrix endpointsanchor icon

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