The Postman tool can be used to make API requests. We have organised TravelTime API endpoints into collections so you can select the request you need to make and run it quickly. The tutorial below discusses just the Time Map endpoint. This endpoint outputs a list of coordinates that shows the perimeter of where’s reachable within a travel time limit. These coordinates can be used to display a travel time polygon on a map.
What is a travel time polygon?
The image below is a visualisation of a travel time polygon showing all locations that are reachable within a 30 minute travel time from London’s Trafalgar Square assuming the user departs the origin at 11.30pm. It displays every possible location you could reach within the 30-minute time slot. The request you’re about to make is quite like a blueprint of the shape below, describing the coordinates needed to draw the dark pink outline.
To begin, make sure you have Postman downloaded and have imported our collection. Follow these instructions:
- Download Postman here
- Open Postman once it's downloaded
- With Postman open, click import and then import from link
- Paste this link to the Postman collection https://www.getpostman.com/collections/c998ebcd8a4c721587c5 into URL input
- Click import
Once you’ve completed the step above, click Time Map and navigate over to the ‘Headers’ tab. You’ll see two empty boxes. One is for the API application ID and the other is for the API.
If you followed the previous tutorial, you will have an email showing your API keys. Get keys here, if not. The shorter set of characters you received in the email is the API ID and the longer set is for the key. Paste these values 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.
Search types: departure and arrival
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 your origin location at a set time. For example you may depart a location at 5pm, 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.
The arrival request assumes the reverse - you must arrive at your origin at the specified time. For example, if you want to arrive at your origin location at 5pm, and travel a maximum of 30 minutes, the points returned will show the perimeter of all the places you can depart 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.
Editing your request
The first thing you will need to do is edit the blue text showing the id. Please make sure that each id is unique, as otherwise, it won’t work. This means the departure and arrival id must be different.
You’ll then need coordinates for your “lat” and “long” fields. The API only accepts a point of origin as coordinates rather than a full address or place name. You can enter a location and get a place name by using our free geocoding tool here.
Image below shows example of free geocoding demo - click here to get coordinates.
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
You then will need to select the mode of transport you wish to use. The shape looks completely different when exploring where’s reachable within a travel time limit depending on which you select.
Choose from these options:
We also have specific modes for certain countries:
- Great Britain only: driving+train
- Netherlands only: cycling+public_transport
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.
What you will get back
Assuming the request was successful, your request should return a long list of lat/long coordinates like the image below. It is also possible you will get an error. To learn more about the error you made have a look at the documentation error codes.