GraphHopper

Instructions to get you started with using OS MRN in GraphHopper.

GraphHopper is an open source routing engine for OpenStreetMap (OSM).

What you need

• Java Virtual Machine (JVM) (Java 17+)

• Node.js and Node Package Manager (npm)

To find out if you have Java installed:

1. Open PowerShell / Command Prompt (Windows) or Shell (Linux) and type:

java -version

1. 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 'What you need'.

To see if you already have Node.js and npm installed and check the installed version:

1. Run the following commands:

node -v
npm -v

If they are not installed, please follow the 'Downloading and installing Node.js and npm' instructions on the npm Docs site.

GraphHopper Routing Engine

The GraphHopper repository on GitHub 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 OS MRN, you require the following files (ensure that they are stored in the same directory):

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

• A YAML configuration file (config-example.yml)

• OS MRN Protocolbuffer Binary Format (PBF) data downloaded from the OS Data Hub (OSMulti-modalRoutingNetwork.pbf)

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

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

13KB

config-example-multiple.yml

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

profiles:
  - name: car
    vehicle: car
    custom_model:
      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.

This means that there is one final configuration change you need to do which will force GraphHopper to read every type of link:

1. Use Ctrl+F to search the config-example-multiple.ymlfile for:

import.osm.ignored_highways: []

1. 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 the "graph-cache" folder 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.

1. Once you see a 'Server - Started' log message, go to http://localhost:8989/ and you'll see an interactive map of your chosen location.

2. Right-click on the map to create a route.

GraphHopper Maps

The GraphHopper Maps repository on GitHub 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 OS Maps API, OS Vector Tile API or OS NGD API – Tiles if you like.

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

To ease getting up-and-running, we have taken a fork of the above repository and made the necessary changes to add in the OS Maps API Outdoor, Light and Road styles. You can clone the forked repository from the OS GraphHopper Maps repository on GitHub.

All you need to then do is add a valid API Key (with a suitable API Plan) to theconfig.js file.

GraphHopper Maps UI showing an example route in the map area which was created using OS MRN in GraphHopper and configured with an OS Maps API Outdoor style basemap.