Distance Matrix API

Getting a TravelTime API key

  • If you don’t already have a TravelTime API key, then you can sign up for one here

  • Look out for an email from support@traveltime.com (if you don’t receive anything within a couple of minutes, try checking your spam folder)

Hello world email
  • The email will include your API credentials, so save these somewhere easily accessible
API key
  • You’ll also find a password which you will need in order to log in to see your API usage in the future, so note this down too
Password

Making a Request

  • Generating a Distance Matrix 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 (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:

  • 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: XXXXXXXX' \
  -H 'X-Api-Key: XXXXXXXX' \
  -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"
        ],
        "transportation": {
          "type": "driving"
        },
        "departure_time": "2021-09-21T08:00:00Z",
        "travel_time": 3600,
        "properties": [
          "travel_time",
          "distance"
        ]
      }
    ]
  }'

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": 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 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