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)

• The email will include your API credentials, so save these somewhere easily accessible

• 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

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"
        ]
      }
    ]
  }'

• 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