How to Create Animated Isochrones By Time of Day with the TravelTime API

Why are isochrones useful?    

Isochrones are useful for visualising how far you can realistically travel within a period of time by a particular transport mode. 

For example, you can show how, in a busy city, the areas you can travel to within a time limit change throughout the day.

The isochrone video below shows how far you can travel in one hour by public transport from Grand Central Station over a 24-hour period:

‍

What you'll need

The project for this visualisation is openly available on our GitHub.

The project uses several open-source tools:

1. Leaflet

‍We'll use Leaflet, a JavaScript library for interactive maps, to create the map. Leaflet is useful for anyone making a map-related application.

For this particular project, we use React Leaflet and a Leaflet plugin, which is used to capture all layers of the Leaflet map and save them as a screenshot. 

2. Next.js

‍A react framework tool that lets you develop full-stack web applications quickly. 

‍3. TravelTime nodejs SDK

‍Our nodejs SDK can be used to access the TravelTime API's /time-map (isochrone) endpoint. 

Our tool repository has a readme file on how to use and configure these tools for the purposes of this tutorial.

How does it work?

To create the final isochrones, the application first draws a coloured square polygon to fill the map. 

The TravelTime API response is then mapped on top to cut “holes” out of the square polygon. 

This object is converted into geoJSON and is displayed on the map. This is how we achieve the look of a transport isochrone on an otherwise colourful map. 

Note: If you’d like to create plain isochrones, you can do this using our Developer Isochrone Playground.

‍

Step 1: Clone or download the code repository and install dependencies

For simplicity, we recommend using an IDE (integrated development environment) to work with the code. However, if you don’t have one, we'd recommend using a source-code editor such as VSCode.

You’ll need to download or clone the repository screenshot capture tool. Here is a detailed guide on how to do so.

When you have cloned the repository, the only major dependency required to run the application on your computer is Node.js. If you don’t have Node on your machine, you can get it here.

‍

Step 2: Get a free TravelTime API key

Since this application sends requests to the TravelTime API, you’ll need to provide authorisation keys to communicate with the API.

You can get a free API key here, which will then be displayed in your dashboard:

Once you have them, you should input them to YOUR_APP_KEY and YOUR_APP_ID environment variables in the isochrone.js file of the project.

‍

Step 3: Run the application

You can now run the application using these commands:

• Npm install: This will install a Node package manager. You can type npm -v to make sure you have installed it correctly.

• Npm run dev: This is the main command to run the application

Then open the URL http://localhost:3000/ and click “Start capture” in the top right corner of the window. 

This will start the capture of screenshots and you'll be able to download them to the default download location on your computer.

If the downloads don’t start, you may need to give permissions to the browser to access your file system or download multiple files.

‍

Step 4: Configure the project with your settings

The application can be easily configured in the config.json file of the project. 

You can adjust various parameters, such as the starting point, screenshot resolution, visual presentation, etc.

Here is the full list of parameters - all configurations are optional apart from the mode selection:

• coords: map and marker centre and request coords
• resolution: css height and width property strings in case you need to set a particular resolution. Will default to full screen if left empty.
• zoom: default map zoom level
• mode: changes the capture mode. Should be either "date" or "traveltime"
• startHour: sets starting hour for API requests.
• locationName: location name used in traveltime mode
• defaultTraveltime: sets API request traveltime in date mode
• colors: object to configure your isochrone colour via hex colour codes
• gmtModifier: GMT date modifier between -11 and +14. Add this if you wish to add a timezone to your request, otherwise UTC will be used
• isosConversionOffset: value to offset Javascript ISO date conversion

All configurations are optional apart from the mode selection.

The tool itself can be run in two modes that can be set in the configuration:

1. Date: This mode will save screenshots by incrementing the date one minute at a time.
2. Traveltime: This mode does the same as date; however, the start time will remain constant while the travel time is incremented by a minute on every request.

‍

Step 5: Create a timelapse video from the downloaded screenshots

To make the video from your screenshots, you may use any video editor of your choice.

However, if you’re a Linux user, there is a very quick way to make a video right in the terminal.

Note: The solution below  will only work on Linux-based platforms.

We've used FFmpeg, an open-source software project that can be used for videos. With FFmpeg, we can create a video right on the terminal.

To install ffmpeg, type in the terminal:

sudo apt install ffmpeg

Have the terminal opened in the folder you have the screenshots from our tool and use the command:

ffmpeg -framerate 6 -i image-%00d.png -c:v libx264 -profile:v high -crf 20 -pix_fmt yuv420p output.mp4

This will create a video called output.mp4 in 6 frames per second in high detail at 1920x1080px resolution.

You can refer to the ffmpeg documentation for more detailed settings, but with our tool you only may need to change the name of the output file or the frame rate.

‍

Summary

These are all the steps you need to take to make a detailed isochrone video showing all reachable locations on a map over a period of time. 

All of the project code is openly available in our repository for you to download. We’ve provided a variety of configuration options, but you’re free to tailor the code to your needs. 

Once you have the screenshots from our capture tool, you can use any video editor or Linux terminal to create videos with timelapses of reachable areas.

Creating isochrones is only one way of using the TravelTime API — why stop here?

To learn more about what you can do with the TravelTime API, such as creating a matrix of travel times, check out our documentation.