OpenSourceRoutingMachine.jl

A thin Julia wrapper for OSRM (Open Source Routing Machine), a high-performance routing engine for road networks. Use it to build routing graphs from OpenStreetMap data and query them for routes, duration/distance matrices, map matching, and more — all from within Julia.

Modules

The package structure consists of a core module and several submodules.

The core module OpenSourceRoutingMachine provides the constructor OSRM for creating an OSRM instance and setter and getter functions for basic configuration.

The rest of the functionality is organized in submodules with the following features:

• Graph: Builds OSRM graphs from OpenStreetMap data
• Nearest: Find the nearest waypoint in a road network for a given position
• Route: Find a route between waypoints containing detailed information
• Table: Find distance/duration matrices between multiple source and destination waypoints
• Match: Find a route by map matching noisy GPS traces to a road network
• Trip: Find a route by solving the traveling salesman problem
• Tile: Retrieve road network geometry as vector tiles

All modules expose the full configuration and parameter handling API of OSRM through setter and getter functions, providing fine-grained control over query behavior.

All query modules (Nearest, Route, Table, Match, Trip) return by default an object whose types are auto-generated (see gen/generate.jl) from OSRM's FlatBuffers schema files. Alternatively, one can receive the binary FlatBuffers response directly.

The Tile module is the exception — it returns road network geometry in MVT format (Mapbox Vector Tiles).

Installation

using Pkg
Pkg.add("OpenSourceRoutingMachine")

Workflow

Using this package follows three steps:

1. Build a routing graph from OpenStreetMap data using the Graph module (one-time step per dataset/profile).
2. Create an OSRM instance pointing to the built graph files.
3. Run queries (route, table, nearest, match, trip, tile) by creating a parameters object, configuring it, and calling the query function.

Usage examples

Graph building

The Graph module builds OSRM routing graphs from OpenStreetMap data by wrapping OSRM's CLI tools.

OSRM can handle different OSM data formats, including OSM XML and PBF (Protocol Buffer Format).

OSRM supports two graph types: MLD (Multi-Level Dijkstra) and CH (Contraction Hierarchies). MLD is the recommended graph type for most use cases.

Each graph is tailored for a specific routing profile that defines how different road types and conditions are weighted. OSRM provides three built-in profiles: car, bicycle, and foot, which can be specified using the Profile enum type. Custom profiles can be used by providing the path to the profile.lua file(s).

The basic workflow for creating an MLD graph for car is as follows:

using OpenSourceRoutingMachine
using OpenSourceRoutingMachine.Graph

# input data
osm_path = "hamburg-latest.osm.pbf"
# output data
osrm_base_path = "hamburg-latest.osrm"   # base path for all graph files

# Build MLD graph (recommended for most use cases)
extract(osm_path; profile = PROFILE_CAR)
partition(osrm_base_path)
customize(osrm_base_path)

When you create an OSRM instance with the base path, it loads these graph files automatically.

OSRM instance

Once the graph is built, you can create an OSRM instance to use the graph.

The OSRM instance is created with the base path of the graph data files. It also contains configuration settings for the OSRM instance.

using OpenSourceRoutingMachine
# create the OSRM instance
osrm_base_path = "hamburg-latest.osrm"
osrm = OSRM(osrm_base_path)
# set the default snapping radius to 100 meters
set_default_radius!(osrm, 100.0)
get_default_radius(osrm)
# see the documentation for more parameters

This instance can then be used with the submodule functionalities for querying.

Coordinate order

Important: Position(longitude, latitude) takes longitude first, then latitude. This follows the GeoJSON convention but differs from the "latitude, longitude" order many mapping tools use. For example, Hamburg city center is Position(9.9937, 53.5511) — longitude 9.99, latitude 53.55.

Nearest query

Find the nearest point on the road network for a given position using nearest(osrm, params).

using OpenSourceRoutingMachine.Nearest

params = NearestParams()
add_coordinate!(params, Position(9.9937, 53.5511))
set_number_of_results!(params, 5)  # Get 5 nearest points
# see the documentation for more parameters

response = nearest(osrm, params; deserialize = true)

By default (deserialize = true), the FlatBuffers binary response is deserialized into an FBResult — a tree of native Julia structs you can inspect and traverse directly. Pass deserialize = false to get the raw Vector{UInt8} instead, useful for custom processing or forwarding without parsing:

response = nearest(osrm, params; deserialize = false)  # raw FlatBuffers bytes

This option applies to all FlatBuffers query functions: nearest, route, match, table, and trip.

Route query

The Route module provides the functionality to calculate the shortest path between two or more waypoints.

The main function is route(osrm, params), which takes the OSRM instance and a route-specific parameters object as input.

For more details on the response options, see the Nearest example above.

using OpenSourceRoutingMachine.Route

# Create route parameters
params = RouteParams()
set_geometries!(params, GEOMETRIES_GEOJSON) # geometry in uncompressed format
set_overview!(params, OVERVIEW_FULL) # detailed geometry information
set_steps!(params, true) # include steps in the response
set_annotations!(params, ANNOTATIONS_ALL) # include all annotations
add_coordinate!(params, Position(9.9937, 53.5511))  # Start: Hamburg city center
add_coordinate!(params, Position(9.9882, 53.6304))  # End: Hamburg airport
# see the documentation for more parameters

# Calculate route
response = route(osrm, params)

Table query

The Table module provides the functionality to calculate the distance/duration matrices between multiple waypoints.

The main function is table(osrm, params), which takes the OSRM instance and a table-specific parameters object as input.

For more details on the response options, see the Nearest example above.

using OpenSourceRoutingMachine.Table

params = TableParams()
# Add coordinates first
add_coordinate!(params, Position(9.9937, 53.5511))
add_coordinate!(params, Position(9.9882, 53.6304))
add_coordinate!(params, Position(9.9667, 53.5417))
add_coordinate!(params, Position(9.9352, 53.5528))
# Mark which coordinates are origins and destinations
add_source!(params, 1)       # first coordinate
add_source!(params, 2)       # second coordinate
add_destination!(params, 3)  # third coordinate
add_destination!(params, 4)  # fourth coordinate
# see the documentation for more parameters

response = table(osrm, params)

Match query

The Match module provides the functionality to map noisy GPS traces to a road network.

The main function is match(osrm, params), which takes the OSRM instance and a match-specific parameters object as input.

For more details on the response options, see the Nearest example above.

using OpenSourceRoutingMachine.Match

params = MatchParams()
set_geometries!(params, GEOMETRIES_GEOJSON) # geometry in uncompressed format
set_overview!(params, OVERVIEW_FULL) # detailed geometry information
set_alternatives!(params, false)  # no alternatives
add_coordinate!(params, Position(9.9937, 53.5511))
add_coordinate!(params, Position(9.9940, 53.5512))
add_coordinate!(params, Position(9.9945, 53.5513))
# see the documentation for more parameters

response = match(osrm, params)

Trip query

The Trip module provides the functionality to solve the traveling salesman problem, finding the optimal order to visit multiple waypoints.

The main function is trip(osrm, params), which takes the OSRM instance and a trip-specific parameters object as input.

For more details on the response options, see the Nearest example above.

using OpenSourceRoutingMachine.Trip

params = TripParams()
set_geometries!(params, GEOMETRIES_GEOJSON) # geometry in uncompressed format
set_overview!(params, OVERVIEW_FULL) # detailed geometry information
set_alternatives!(params, false)  # no alternatives
add_coordinate!(params, Position(9.9937, 53.5511))
add_coordinate!(params, Position(9.9940, 53.5512))
add_coordinate!(params, Position(9.9945, 53.5513))
# see the documentation for more parameters

response = trip(osrm, params)

Tile query

The Tile module provides the functionality to retrieve road network geometry as vector tiles in MVT format.

The main function is tile(osrm, params), which takes the OSRM instance and a tile-specific parameters object as input.

using OpenSourceRoutingMachine.Tile

params = TileParams()
set_x!(params, 4500)  # Tile X coordinate
set_y!(params, 2700)  # Tile Y coordinate
set_z!(params, 13)    # Zoom level
# see the documentation for more parameters

response = tile(osrm, params)

Copyright (c) 2025–2026 MOVIRO GmbH

Licensed under the MIT License.