GraphHopper is an open source routing engine for OpenStreetMap.


GraphHopper Routing Engine

The graphhopper GitHub repository (https://github.com/graphhopper/graphhopper) explains how to download and run the GraphHopper Routing Engine as a Java library or standalone web server to calculate the distance, time, turn-by-turn instructions and many road attributes for a route between two or more points.

To create routes using the OS MRN you require the following files (ensure that they are stored in the same directory):

  1. The graphhopper-web-8.0.jar JAR (Java ARchive) package file containing the GraphHopper Maps UI and the web service.

  2. A YAML configuration file.

  3. Routable network data in OpenStreetmap PBF format.

To find out if you have Java installed, open PowerShell / Command Prompt (Windows) or Shell (Linux) and type:

java -version

Press Enter. If Java is installed, you should see a few lines of text detailing which version you have installed.

If you get something along the lines of "java is not recognized ..." please download JVM [or OpenJDK] using the link above in Prerequisites.

The config-example.yml provided in the repository enables basic vehicular (car) routing.

We have created a custom version of this file (config-example-multiple.yml) which allows for vehicular (car) routing with turn costs, as well as the calculation of pedestrian (walking) and cycling routes.

Compared to the basic configuration file you will see that the custom version enables turn restrictions (under the car profile) and includes additional profiles to enable cycling and walking:

  - name: car
    vehicle: car
      distance_influence: 70
    turn_costs: true
    u_turn_costs: 60

  - name: bike
    vehicle: bike
    custom_model_files: [bike.json]

  - name: foot
    vehicle: foot
    custom_model_files: []


  • The turn_costs line tells GraphHopper to force the car travel mode ("profile") to respect turn restrictions.

  • The u_turn_costs line tells GraphHopper how long a U-turn should add to your route (in this case 60 seconds).

  • The custom_model_files are required but can be empty. The optional bike.json is a reference to a specification to get cycle routing to prefer less busy roads, for example.

By default (i.e. only using driving routing) GraphHopper knows there's no need to read in footpaths, cycleways, etc. Now that you want the additional "profiles", you need to change that.

One final configuration change will force GraphHopper to read every type of link. Use Ctrl+F to search the config-example-multiple.ymlfile for:

import.osm.ignored_highways: []

Download the OpenStreetmap PBF format OS MRN data from the OS Data Hub. Please see Creating data packages and downloading data for further guidance.

You can now start the GraphHopper Maps UI and the web service as follows:

java -D"dw.graphhopper.datareader.file=OSMulti-modalRoutingNetwork.pbf" -jar graphhopper-web-8.0.jar server config-example-multiple.yml

This reads in the OS MRN data and sets everything up. It might take a few minutes the first time you run this command, but when complete you will see two folders have been added to your directory: graph-cache and logs.

When you start GraphHopper again, it will see the data contained within graph-cache and know that it doesn't have to re-read the PBF file. However, if you update your .pbf or .yml files, make sure you delete graph-cache before starting GraphHopper again.

Once you see a 'Server - Started' log message go to http://localhost:8989/ and you'll see an interactive map of your chosen location. You should be able to right click on the map to create a route.

GraphHopper Maps

The graphhopper-maps GitHub repository (https://github.com/graphhopper/graphhopper-maps) supplements the GraphHopper Routing Engine as a customisable version of the route planner user interface.

This repository contains instructions on how to start development and how to make configuration changes, including adding different map tile providers. You can add the OS Maps API, OS Vector Tile API or OS NGD API – Tiles.

You will also be able to point to the web service hosted at http://localhost:8989/.

To ease getting up-and-running, we took a fork of the above repository (graphhopper-maps) and made the necessary changes to add in the OS Maps API Outdoor, Light and Road styles. You can clone the forked repository from https://github.com/OrdnanceSurvey/graphhopper-maps.

All you need to then do is add a valid API key (with a suitable API Plan) to the config.js file.

Last updated