TravelTime Docs logo
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

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

{
  "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"
      ]
    }
  ]
}
  • 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 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