Isochrones show how far you can travel within a specified time limit and by a specified mode of transport.
You can use isochrones on your website or app to show users which locations they can travel to within their preferred travel time and by their specified mode of transport.
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.
- CodePen. You can insert the code snippets provided in this tutorial into a CodePen integrated development window where you can manipulate the code and see a live result. To make the sample work and draw the isochrone, you’ll first need to insert a TravelTime API key into the CodePen.
How the TravelTime Isochrone API works
In this example, we'll use the TravelTime Geocoder to get coordinates of the White House, Washington DC. Then we'll send those coordinates as a search back to the API.
The received isochrone data will be drawn on a Leaflet map. The end result will be a map showing all the areas that can be reached within 60 minutes from the start location using public transport. We'll also be able to choose from different transport modes, including driving, walking and cycling.
To create an isochrone, you'll need to provide parameters to the API search request, including:
- Departure or arrival location
- Mode of transport
- Travel time limit
- Time of the day
You can test this for yourself with our interactive Isochrone API Playground.
Once the request is made, the TravelTime API receives the request and returns a JSON response. The response includes coordinates for points. These points show the boundaries of shapes reachable within the travel time.
The image below is an example of an isochrone created with the TravelTime API:
TravelTime Isochrone API request and response
Communication with the API works by sending a JSON format request and the API returns a JSON format response with the polygon data that we will see drawn in the sample code.
Here is how an API request looks without header information:
The JSON response after a successful API request includes coordinates. These points show the boundaries of shapes reachable within the corresponding travel time.
Visualising your response on a map
Now we can visualise this response on a map. Let’s explore the sample code — this is also available in the CodePen development environment.
Writing your code sample
To write your code sample, we first need to define parameters for the search. To do this, we'll need to:
- Convert the name of the start location into coordinates using the TravelTime Geocoder
- Enter the departure time in the ISO format
- Convert the one-hour travel time into seconds
These values usually would be in the JSON request; in our sample, we're setting them as variables
To execute a request to the TravelTime API, you'll need an API key. You can get a free API key here.
The API key is added to the header information of the API request, into variables APPLICATION_ID and API_KEY. These are needed to authenticate the request and usually sit on the server side of your application.
Using the TravelTime Geocoder
For the starting location, we specified The White House, Washington DC. However, the Isochrone API only accepts latitude and longitude coordinates.
To change the address into coordinates we can use the TravelTime geocoding endpoint.
Generating a request to the TravelTime Isochrone API
Now that we have everything we need for the request, we can use the code that would generate the request to the Isochrone API.
A JSON departure_search is formed and sent in a HTTP request.
Drawing the result
In this sample we are using free Leaflet.js for the interactive map and Mapbox map tiles.
mymap variable sets the starting location of the map when the code sample loads.
Drawing the isochrone itself is handled by this script.
To see all of the mentioned code in action, please try our CodePen.