OS Multi-modal Routing Network (OS MRN) is designed for use in routing applications. Numerous different routing software applications are available.

This guide includes instructions to get you started with using OS MRN in three open-source routing applications:

• pgRouting – for GeoPackage (GPKG) and Protocolbuffer Binary Format (PBF)

• GraphHopper – for PBF

• OpenTripPlanner – for PBF

The guide also has a page on working with OpenStreetMap (OSM) files, where you will find guidance on:

• What tools you can use to convert from PBF to OSM XML

• Sorting OSM files

How to get this product

OS MRN data can be downloaded from the OS Data Hub (for further guidance, please see Creating data packages and downloading data).

OpenTripPlanner (OTP) is an open source multi-modal trip planner, focussing on travel by scheduled public transportation in combination with bicycling, walking, and mobility services, including bike share and ride hailing.

What you need

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

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'.

Basic usage

In terms of creating a transit network using OS MRN, you'll require the following files (ensure that they are stored in the same directory):

• The otp-2.5.0-shaded.jar "shaded" JAR (Java ARchive) containing OTP and all other libraries needed for it to work.

• Some General Transit Feed Specification (GTFS) data for Transit Schedules and Stops, for example, Bus Open Data Service (BODS).

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

The OpenTripPlanner Basic Tutorial provides a detailed set on instructions of how to get the interactive OTP instance up-and-running, but fundamentally the steps are as follows:

1. Open PowerShell / Command Prompt (Windows) or Shell (Linux) and navigate to the folder where the OTP JAR, BODS GTFS, and OS MRN PBF files have been stored.

2. Run the following command to start the service: java -Xmx8G -jar otp-2.5.0-shaded.jar --build --serve . --port 8801.

3. Go to http://localhost:8801/ in a web browser.

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:

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: []

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 the config.js file.

pgRouting extends the PostGIS / PostgreSQL geospatial database to provide routing and other network analysis functionality.

What you need

• PostgreSQL database

• PostGIS spatial extension

• pgAdmin4 (or any other database explorer)

• QGIS (optional – see note below)

Introduction to graph data and routing

A graph data structure is made up of nodes and edges. With OS MRN, these are represented by the mrn_ntwk_transportnode and mrn_ntwk_transportlink layers.

Nodes are points that represent junctions connecting one or more paths on a network. This is where a decision is made on where to turn next (or stop if you are at the end of the route). All nodes must connect to an edge.

Edges connect two or more nodes, and represent the distance between them. They can be directed (for example, one-way restrictions) or undirected (any direction allowed). Their default direction will be in the direction the edge was digitised, from startpoint to endpoint.

The distance is a reflection of the cost to travel along that edge. At the base level, this would be the length of the edge (in metres), but can be extended with maths to incorporate things like the speed of travel along the edge.

Using other data you may have, cost can be extended even further, for example, to take into account factors that might make a traveller use a particular route more (such as scenery, traffic, points of interest and gradient).

With pgRouting, these costs can be applied to each edge in a particular direction, that is, in direction (the direction of digitising) and in reverse direction. This enables the user to have more control on what the routing algorithms look for.

Routing algorithms

Routing algorithms are a set of rules used to determine the best path between two or more points. Some of the common ones used are:

• pgr_dijkstra – The classic shortest path algorithm, from one node to another, using a directed or non-directed graph.

• pgr_drivingdistance – Using Dijkstra, finds all nodes that are reachable within a set distance using a directed or non-directed graph. Produces results that can then be visualised as an isochrone polygon.

• pgr_trsp (turn restriction shortest path) – Runs similar to Dijkstra, with the addition of using restriction information. With OS MRN, this restriction data is available in the mrn_ntwk_turnrestriction layer. These turn restrictions reference the edges from the network layer and are used as a lookup as the algorithm works.

Checking that PostGIS and pgRouting are enabled

In more recent versions of PostgreSQL, both PostGIS and pgRouting are enabled as standard, ready to be used.

To check this:

1. Load pgAdmin4 (or your chosen database explorer).

2. Highlight your database.

3. Open a SQL window and run:

CREATE EXTENSION postgis;

ERROR: extension "postgis" already exists
SQL state: 42710

In the example above, PostGIS was already enabled. However, in the example below, pgRouting wasn't enabled, but is now ready to be used within the selected database:

CREATE EXTENSION pgrouting;

Query returned successfully in 151 msec.

Loading the GeoPackage

The easiest way to load the GeoPackage (GPKG) into PostgreSQL via ogr2ogr is to use the OSGeo4W Shell that is provided with the QGIS install package:

1. Before loading the GPKG, check that environment variables have been set up so that PostgreSQL will be recognised by the command prompt. Admin permissions are required to edit these variables.

2. Add the folder location of your PostgreSQL install to the User->Path and System->Path variables.

3. Once you have done this, open the OSGeo4W Shell (as shown above), and type in ogr2ogr. If everything is setup correctly, you should see:

1. To then load the OS MRN GPKG into your PostgreSQL database, navigate to the location of the file, and type the following:

ogr2ogr -f PostgreSQL -progress -gt 65000 -a_srs EPSG:4326 -lco SCHEMA=<schema> -lco GEOMETRY_NAME=geometry PG:"dbname=<dbname> host=<host> port=<port> user=<user> password=<password>" OSMulti-modalRoutingNetwork.gpkg

You could alternatively use the following command (where /vsizip/ is a file handler that allows reading ZIP archives on-the-fly without decompressing them beforehand):

ogr2ogr -f PostgreSQL -progress -gt 65000 -a_srs EPSG:4326 -lco SCHEMA=<schema> -lco GEOMETRY_NAME=geometry PG:"dbname=<dbname> host=<host> port=<port> user=<user> password=<password>" /vsizip/OSMulti-modalRoutingNetwork.zip/OSMulti-modalRoutingNetwork.gpkg

This will load the three layers of the OS MRN GPKG into the defined database schema, and create the relevant spatial indexes.

1. You can now add some further attribute indexes for the unique identifiers:

CREATE INDEX mrn_ntwk_turnrestriction_wayid_idx ON <schema>.mrn_ntwk_transportlink USING btree (wayid);
CREATE INDEX mrn_ntwk_turnrestriction_nodeid_idx ON <schema>.mrn_ntwk_transportnode USING btree (nodeid);
CREATE INDEX mrn_ntwk_turnrestriction_relationid_idx ON <schema>.mrn_ntwk_turnrestriction USING btree (relationid);

1. With all the indexes added, you can create a basic edge table on which to start routing:

CREATE TABLE <schema>.edge_table AS
SELECT
  wayid AS id,
  name,
  foot,
  highway,
  railway,
  rail,
  ferry,
  toll,
  junction,
  route,
  ford,
  bridge,
  tunnel,
  service,
  oneway,
  ST_Length(geometry::geography) AS length,
  (STRING_TO_ARRAY(nodes, ',')::int[])[1] AS source, -- converts the nodes string to an array and extracts the first index item
  (STRING_TO_ARRAY(nodes, ',')::int[])[array_upper((STRING_TO_ARRAY(nodes, ',')::int[]), 1)] AS target, -- converts the nodes string to an array and extracts the last index item
  CASE
    WHEN oneway = '-1' THEN -1
    ELSE ST_Length(geometry::geography) -- returns the geometry length in metres
  END AS cost,
  CASE
    WHEN oneway = 'yes' THEN -1
    ELSE ST_Length(geometry::geography) -- returns the geometry length in metres
  END AS reverse_cost,
  geometry
FROM <schema>.mrn_ntwk_transportlink;

CREATE UNIQUE INDEX edge_table_id_idx ON <schema>.edge_table (id);
CREATE INDEX edge_table_source_idx ON <schema>.edge_table (source);
CREATE INDEX edge_table_target_idx ON <schema>.edge_table (target);

CREATE INDEX edge_table_geometry_idx
  ON <schema>.edge_table
  USING gist
  (geometry);

Loading the Protocolbuffer Binary Format

osm2po is a cross platform tool written in Java that can be used to parse OS MRN PBF data and make it routable in pgRouting.

1. To find out if you have Java installed, 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] from https://adoptium.net/en-GB/.

2. Once osm2po is downloaded and extracted, open and edit the config file to satisfy your usage requirements (for example, change the wtr.finalMask = car line (use Ctrl+F to search the file) to car,foot,bike travel types).

3. Uncomment the following line (this helps with getting the topology into a format pgRouting likes):

postp.0.class = de.cm.osm2po.plugins.postp.PgRoutingWriter

1. When this is done, and assuming Java is installed and accessible, open a command prompt and navigate to the location of the .pbf file, and then run the following:

java -jar osm2po-core-5.5.11-signed.jar cmd=c prefix=osm2po OSMulti-modalRoutingNetwork.pbf

This will create the .sql file version of the .pbf file.

1. Import the .sql file version of the .pbf file to the PostgreSQL database using the following:

psql -h <host name> -U <username> -d <database name> -q -f <filename>.sql

In this newly created table, each record should have a source and target node, and an integer classification. Cost and reverse cost columns are also applied. Cost in this case is worked out using distance (in km) and speed (kmh) defined in the config file.

Running a test route with pgRouting (Dijkstra)

The mandatory things pgRouting needs to be able to route with are a routing table, start node and end node. Once the routing table is created, pgRouting can be run straight away.

For the following example, OS MRN sample data has been used, with the GPKG data being loaded into PostgreSQL via ogr2ogr (with the SQL run to create basic edge table). A couple of waypoints have been selected in Exeter, and a sample Dijkstra route query can look like the one below:

WITH start AS (
  SELECT source
    FROM <schema>.edge_table
    ORDER BY geometry <-> ST_SetSRID(
      ST_GeomFromText('POINT (-3.53532 50.72046)'), 4326)
    LIMIT 1
),
destination AS (
  SELECT source
    FROM <schema>.edge_table
    ORDER BY geometry <-> ST_SetSRID(
      ST_GeomFromText('POINT (-3.52133 50.72294)'), 4326)
    LIMIT 1
)
SELECT ST_Union(geometry) AS route
  FROM pgr_dijkstra(
    'SELECT id, source, target, cost, reverse_cost FROM <schema>.edge_table',
    ARRAY(SELECT source FROM start),
    ARRAY(SELECT source FROM destination)
  ) AS di
  JOIN <schema>.edge_table AS pt
  ON di.edge = pt.id;

This route query is made up of three parts:

• First, the 'start' section finds the start node to use from the network that is closest to the point given. This could be fed in to the query in multiple ways, such as clicking on a web map, or using a plugin.

• Second, the 'destination' section finds the start node closest to the destination point given.

• The final part includes the pgr_dijkstra function, reading in the start and destination ids, and returns a merged geometry of links that form the route.

When visualised in QGIS, the result should look similar to this:

It should be noted that the above route query does not take any of the additional OS MRN attribution into account. This means that every edge will be considered when calculating the shortest path. We can therefore apply some additional logic in the SELECT statement to facilitate either vehicular or pedestrian routing:

• Vehicular routing – Determines the best vehicular route where the edges are deemed to be roads.

'SELECT id, source, target, cost, reverse_cost
  FROM <schema>.edge_table
  WHERE "rail" = ''no''
    AND "highway" IN (
      ''motorway'',
      ''motorway_link'',
      ''trunk'',
      ''trunk_link'',
      ''primary'',
      ''primary_link'',
      ''secondary'',
      ''secondary_link'',
      ''tertiary'',
      ''tertiary_link'',
      ''unclassified'',
      ''residential''
    )'

• Pedestrian routing – Determines where the edges can be traversed by foot and whether there is designated infrastructure for walking.

'SELECT id, source, target, cost, reverse_cost
  FROM <schema>.edge_table
  WHERE "foot" != ''no''
    AND "rail" = ''no''
    AND "highway" IS NOT NULL'

Converting PBF to OSM XML

A lot of routing software used in the OpenStreetMap (OSM) project supports Protocolbuffer Binary Format (PBF). There are several tools to convert from PBF to OSM XML and vice versa, if required, including Osmconvert, Osmosis and Osmium:

Sorting OSM files

OSM files are usually sorted in a specific way: first the nodes ordered by ID, then ways ordered by ID, then relations ordered by ID. But this is not necessarily always the case.

To check if a file is sorted, in Osmium use fileinfo :

> osmium fileinfo -e input.osm.pbf
...
Objects ordered (by type and id): yes
...

To sort a file using Osmium:

> osmium sort input.osm.pbf -o output.osm.pbf

To sort a file using Osmosis:

osmosis --read-pbf input.osm.pbf --sort --write-pbf output.osm.pbf