In this tutorial, you'll learn how to use the TravelTime Isochrone API within Postman to output a list of coordinates that show the perimeter of where’s reachable within a travel time limit. You can use these coordinates to display travel times on a map.
To follow along with the tutorial, you’ll need the following:
- The TravelTime Isochrone API. The Isochrone API calculates all areas that are reachable within a specified travel time from a start location by any transport mode and allows you to display this on a map. If you’re new to TravelTime, you can sign up for a free API key here.
- Postman. You'll need this to download the TravelTime Postman collection. You can download Postman here.
What is an isochrone?
Isochrones show the areas that you can reach within a specified time by a specified mode of transport.
The TravelTime Isochrone API allows you to use isochrones in your website or app to enable users to see where they can travel within their maximum travel time limit by their desired mode of transport.
The image below is is an isochrone that shows all locations that are reachable within a 30-minute travel time from London’s Trafalgar Square, assuming the user departs at 1.30 pm.
This isochrone was created with our free TravelTime app - you can try the app for yourself here.
The request you’re about to make is quite like a blueprint of the shape below, describing the coordinates needed to draw the outline of the isochrone shape.
1. Getting started in Postman
Once you've downloaded Postman, open the tool and click Import and then Import from link.
Paste this link to the Postman collection: https://www.getpostman.com/collections/c998ebcd8a4c721587c5 into URL input and click Import.
Once you’ve completed the step above, click Time Map and navigate over to the Headers tab.
Here, you’ll see two empty boxes. One is for the API application ID and the other is for the API.
To continue with the tutorial, you'll need a TravelTime API key. You can get a free API key here.
Once you’ve verified your email and logged in, be able to access your TravelTime account dashboard. Here, you can find the API credentials that you will need to use when making any requests to the TravelTime API.
In the Postman application, paste the values for your TravelTime Application ID and Application Keys in the two empty boxes ‘X-Application-Id’ and ‘X-Api-Key’.
Now navigate over to the body tab as indicated by the orange box.
2. Make your departure and arrival requests
1. Departure search
The code shows one departure request (top orange arrow) and one arrival request (bottom orange arrow).
A departure request shows where is reachable, assuming you depart from your origin location at a set time.
For example, you may depart from a location at 5 pm and travel a maximum of 30 minutes, so the points returned will show the perimeter of all the places you can reach before 5.30pm. The standard Postman assumes you need to depart at the time you make the search.
2. Arrival search
The arrival request assumes that you must arrive at your origin at the specified time.
For example, if you want to arrive at your origin location at 5 pm and travel a maximum of 30 minutes, the points returned will show the perimeter of all the places you can depart from at 4.30pm to arrive at the origin at 5 pm or earlier.
These are two different requests within a single API call. It means you get two lots of information:
- The latitude and longitude coordinates for the perimeter of the departure search polygon
- The latitude and longitude coordinates for the perimeter of the arrival search polygon
The image below is a visualisation of what you get back if you plotted the coordinates on a map. The blue shows the perimeter of an arrival search and the pink shows the departure search.
3. Edit your request
The first thing you will need to do is edit the blue text showing the id.
Note: Please make sure that each id is unique as otherwise, it won’t work. This means that the departure and arrival id must be different.
To geocode, you’ll then need coordinates for your “lat” and “long” fields. The TravelTime API only accepts a point of origin as coordinates rather than a full address or place name.
Things to watch out for when using coordinates:
- Include the comma after the initial latitude coordinate
- Make sure to use the minus symbol when the coordinate requires it, it will say this within the geocoding tool above
5. Select your transport modes
The TravelTime API allows you to make requests for any mode of transport.
For this tutorial, you will need to select the mode of transport you wish to use. The shape of the isochrone will change depending on which mode of transport you select.
Choose from these options:
We also have specific modes for certain countries:
- Great Britain only: driving+train
- Netherlands only: cycling+public_transport
6. Edit the time of travel
This part of the code shows the following:
- The departure time and date in extended ISO-8601 format (YYYY-MM-DDT00:00Z)
- The maximum travel time area listed in seconds. The example above is 15 minutes (900 seconds / 60 seconds in a minute)
This example below shows 30th October 2019 at 11.30pm (23:30). It also has a maximum travel time area of 30 minutes (30*60 seconds)
Now click the send button. This will run your request and you’ll see the response box below your request change.
7. Understanding the API response
Assuming the request was successful, your request should return a long list of lat/long coordinates like the image below.
However, you may get an error. To learn more about the error you made have a look at the documentation error codes.
Now that you've used the TravelTime API in Postman, why not try the API for your project?
With the TravelTime Isochrone API, you can allow your users to see where they can travel to within their maximum travel time for any mode of transport, including public transport, cycling and walking.
And with the TravelTime Matrix API, you can also rank and filter thousands of location search results by travel time.