Contents
A distance matrix shows the travel distance and time between a matrix of origins and destinations.
With the TravelTime API, you can create a distance matrix and easily calculate travel times from thousands of origins to thousands of destinations for any mode of transport.
In this tutorial, we’ll be using the TravelTime API to calculate travel times between many locations.
Getting started with the TravelTime API
With the TravelTime API, you can calculate travel times and distances between thousands of origins and destinationsfor any mode of transport – including public transport, driving and cycling.
The API also allows you to set a travel time cut-off to automatically label points as reachable or unreachable, as you can see in our TravelTime Matrix Playground app below:
How can I use the TravelTime API?
You can use the TravelTime Matrix API in two ways:
- As a standalone API
- Within our plugins forArcGIS, QGIS or Alteryx
Creating matrices with the TravelTime API is done through a credit model. With one matrix credit, you can calculate travel times from one location to up to 2,000 destinations or vice versa.
How to create a distance matrix with the TravelTime API
For this tutorial, you’ll need to first get a free TravelTime API key.
We’ll be using the Time Filter endpoint of the TravelTime API. You can find the documentation for this endpoint here.
To use the Time Filter endpoint, you’ll need to create a simple JSON request. For the examples below, we’ll be using the following parameters: the following parameters are first entered by the user:
- Departure or arrival location
- Mode of transport
- Travel time limit
- Time of the day
Example 1: Calculating travel times from one origin to many destinations
Calculating travel times from one origin to many destinations is also known as a departure search.
For example, we could use this search to calculate the travel times between an app user’s home location and 100 local restaurants to find the one with the shortest travel time.
Below, we’ve created a departure search example request:
To create these, we entered location IDs as a set of lat-long coordinates for 1) London Center 2) Hyde Park and 3) ZSL London Zoo.
Here are the other parameters:
- Departure point:London Center
- Transport type:Bus
- Maximum travel time:30 minutes (however, the TravelTime API only accepts values in seconds, so we’ve input 1800 seconds)
- Time, date:8 am, 9th July 2018
- The range option is enabled and will return up to 3 travel times within a range of 600 seconds in ascending order
What does the code response mean?
The response below lists, in seconds, the travel times from the origin (London Center) to the multiple destinations.
For example, we can see it takes 1723 seconds (or just under 29 minutes) to depart London centre and reach Hyde Park:
There are also three possible travel times from the London Center to Hyde Park. This is because the ‘range’ feature is enabled. This feature calculates results assuming the user can select different routes for the journey.
Finally, you can see that ZSL London Zoo is not reachable. This means that it is not possible to reach the zoo within the 30-minute limit.
You can also adjust the request to get the following responses returned:
- Distance (if driving, walking or cycling)
- Fare data (if using public transport and searching in the UK)
- Route breakdown for all transport modes
Example 2: Calculating a distance matrix from many origins to one destination
Running a matrix calculation between many origins and one destination is also known as an arrival search.
For example, this could be used to calculate the travel times between 100 employee addresses to arrive at one office destination at 9 am.
For this example, we’ve created an example arrival search to show an arrival at the desired destination (London Center) from the multiple origin locations (Hyde Park and ZSL London Zoo).
The parameters are as follows:
- Arrival location:London Center
- Transport type:Public transport
- Maximum travel time:1900 seconds (just over 31 minutes)
- Time, date:8 am, 9th July 2018
See the request below:
What does the code response mean?
The response below lists travel times from multiple origins to the single destination in seconds.
For example, it takes 1723 seconds (or just under 29 minutes) to arrive at London centre when departing from Hyde Park.
Real-life example: Calculating travel times from several addresses to one destination
We’ll now walk through a real-life example of calculating travel times to find the best office location.
Column 1 on the table below shows the employee addresses. These will serve as our departure locations. The first row of locations shows proposed office locations. These will serve as our arrival locations.
To create the travel time matrix, we’ll assume the employees need to reach the office locations by 8 am. To get travel time results, we'll need to create a request that has multiple arrival searches.
For this, we will have 3 departure locations in a single request. One to get travel times to E5 0AA, second to EC4P 4BF and third from EC4M 9EB. We will disable range to get a single travel time result for each search.
Here’s an example request:
In the response below, we get results for all 3 journeys that could be placed into a table to create a travel time matrix:
How to use a distance matrix API
As we’ve seen,a distance matrix APIallows you to do more complex calculations than just a single origin to a single destination.
Here are just a few ways to use a distance matrix API:
1. Calculate travel times for website search
You can use a distance matrix API within a website’s search algorithm to calculate travel times between a user’s start location and possible locations within their desired travel time.
The calculations can then be displayed as a list of results for the user to select from.
For example,property website, Zoopla, uses the TravelTime APIto allow users to search for properties within a specific travel time. On a property search a user enters:
- A target destination: for example, where they work
- Their transport preferences: their preferred mode of transport and maximum time they’re willing to commute
This search area is then cross-referenced to all the points of interest in the Zoopla database (i.e. the properties for sale) and a travel time to each relevant property is listed.
Properties that are reachable within the travel time limit are shown. The houses are displayed both as pins on the map and in a list view:
2. Calculate employee commute times
A distance matrix API can also be used for a commute time analysis to select the best location for an office.
You can use it to calculate travel times between employees’ addresses and potential office locations, and thereby analyse the impact of an office relocation on employees’ commute times.
Create a distance matrix with the TravelTime API
The TravelTime API lets you calculate travel distances and times between many locations for any transport mode. If you’re looking for an alternative distance matrix API provider, check out our distance matrix API comparison.
Not only can you create matrices with the TravelTime API – you can also create isochrones (travel time polygons) to show where you can travel within a time limit, as well as A to B routes for no extra cost.
To learn more about what you can do with the TravelTime API, check out our documentation or sign up for a free API key .
