Tutorial: How to Create Isochrones with Postman and the TravelTime Isochrone API

The Postman API platform can be used to make API requests. We've organised the TravelTime APIs into Postman collections so you can select the request you need to make and run it quickly.

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. 

Prerequisites‍

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, search for TravelTime Developers in Postman Search or go to our Workspace in your browser.

In TravelTime Developers workspace you will find TravelTime API Collection, right click on it to fork the Collection.

Give the repository a name and add it to your Workspace.

You can also fork the environment template from the TravelTime Developers Workspace:

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.

To run requests you’ll need to supply your TravelTime API id and key and set them as your environment variables within your workspace. If you forked the TravelTime Environment, you just need to edit what you already have.

To set any environment variable, create a new environment within Postman, you can do that by clicking the plus icon in the Environments section. If you forked the environment then you will just need to do next step of adding your API keys.

Add your authentication details as api_id and api_key variables to the environment and save. After saving you need to set the environment to active, so check mark is visible next to it's name. On the right side of the screen select to use the environment you have created as the current environment.

If your environment is set up correctly, you should be able to set your authentication Type as API Key and set variable api_id as Key and api_key as Value, set Add to Header:

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.

4. Geocoding

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: 

• cycling
• driving
• public_transport
• walking
• coach
• bus
• train
• ferry
• driving+ferry
• cycling+ferry 

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 .  

Next steps

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.

Check out our documentation to learn more about what you can do with the TravelTime API or sign up for a free API key.