OSRM API Documentation

Appearance

Python API ​

The Python bindings provide access to OSRM's routing services through the osrm package. Install with pip install osrm-bindings.

OSRM ​

The OSRM class is the main entry point. It requires a .osrm.* dataset prepared by the OSRM toolchain.

python
import osrm

# From file
engine = osrm.OSRM("path/to/data.osrm")

# With keyword arguments
engine = osrm.OSRM(
    storage_config="path/to/data.osrm",
    algorithm="CH",                      # or "MLD"
    use_shared_memory=False,
    max_locations_trip=3,
    max_locations_viaroute=3,
    max_locations_distance_table=3,
    max_locations_map_matching=3,
    max_results_nearest=1,
    max_alternatives=1,
    default_radius="unlimited",
)

# Using shared memory (requires osrm-datastore)
engine = osrm.OSRM(use_shared_memory=True)

Parameters ​

  • storage_config str - Path to the .osrm dataset.
  • algorithm str - Routing algorithm: "CH" or "MLD". Default: "CH".
  • use_shared_memory bool - Connect to shared memory datastore. Default: True.
  • dataset_name str - Named shared memory dataset (requires osrm-datastore --dataset_name).
  • memory_file str - Deprecated. Equivalent to use_mmap=True.
  • use_mmap bool - Memory-map files instead of loading into RAM.
  • max_locations_trip int - Max locations in trip queries.
  • max_locations_viaroute int - Max locations in route queries.
  • max_locations_distance_table int - Max locations in table queries.
  • max_locations_map_matching int - Max locations in match queries.
  • max_results_nearest int - Max results in nearest queries.
  • max_alternatives int - Max alternative routes.
  • default_radius float | "unlimited" - Default search radius in meters.

Services ​

All service methods take a parameters object and return a dict-like Object:

python
result = engine.Route(route_params)
print(result["routes"])
print(result["waypoints"])

Route ​

Finds the fastest route between two or more coordinates.

python
params = osrm.RouteParameters(
    coordinates=[(7.41337, 43.72956), (7.41546, 43.73077)],
    steps=True,
    alternatives=2,
    annotations=["speed", "duration"],
    geometries="geojson",
    overview="full",
)
result = engine.Route(params)

RouteParameters ​

Inherits all BaseParameters.

  • steps bool - Return route steps for each leg. Default: False.
  • alternatives int - Number of alternative routes to search for. Default: 0.
  • annotations list[str] - Additional metadata: "none", "duration", "nodes", "distance", "weight", "datasources", "speed", "all". Default: [].
  • geometries str - Geometry format: "polyline", "polyline6", "geojson". Default: "polyline".
  • overview str - Overview geometry: "simplified", "full", "false". Default: "simplified".
  • continue_straight bool | None - Force route to continue straight at waypoints.
  • waypoints list[int] - Indices of coordinates to treat as waypoints. Must include first and last.

Table ​

Computes duration/distance matrices between coordinates.

python
params = osrm.TableParameters(
    coordinates=[(7.41337, 43.72956), (7.41546, 43.73077), (7.41862, 43.73216)],
    sources=[0],
    destinations=[1, 2],
    annotations=["duration", "distance"],
)
result = engine.Table(params)

TableParameters ​

Inherits all BaseParameters.

  • sources list[int] - Indices of source coordinates. Default: all.
  • destinations list[int] - Indices of destination coordinates. Default: all.
  • annotations list[str] - "duration", "distance", "all". Default: ["duration"].
  • fallback_speed float - Speed for crow-flies fallback when no route found.
  • fallback_coordinate_type str - "input" or "snapped".
  • scale_factor float - Scales duration values. Default: 1.0.

Nearest ​

Finds the nearest street segment for a coordinate.

python
params = osrm.NearestParameters(
    coordinates=[(7.41337, 43.72956)],
    number_of_results=3,
)
result = engine.Nearest(params)

NearestParameters ​

Inherits all BaseParameters.

  • number_of_results int - Number of nearest segments to return. Default: 1.

Match ​

Snaps noisy GPS traces to the road network.

python
params = osrm.MatchParameters(
    coordinates=[(7.41337, 43.72956), (7.41546, 43.73077), (7.41862, 43.73216)],
    timestamps=[1424684612, 1424684616, 1424684620],
    radiuses=[5.0, 5.0, 5.0],
    annotations=["speed"],
    geometries="geojson",
)
result = engine.Match(params)

MatchParameters ​

Inherits all RouteParameters and BaseParameters.

  • timestamps list[int] - UNIX timestamps for each coordinate.
  • gaps str - Gap handling: "split" or "ignore". Default: "split".
  • tidy bool - Remove duplicates. Default: False.
  • waypoints list[int] - Indices of coordinates to treat as waypoints.

Trip ​

Solves the Traveling Salesman Problem for the given coordinates.

python
params = osrm.TripParameters(
    coordinates=[(7.41337, 43.72956), (7.41546, 43.73077), (7.41862, 43.73216)],
    source="first",
    destination="last",
    roundtrip=True,
    annotations=["duration"],
    geometries="geojson",
)
result = engine.Trip(params)

TripParameters ​

Inherits all RouteParameters and BaseParameters.

  • source str - "any" or "first". Default: "any".
  • destination str - "any" or "last". Default: "any".
  • roundtrip bool - Return to first location. Default: True.

Tile ​

Generates vector tiles with internal routing graph data.

python
params = osrm.TileParameters(x=17059, y=11948, z=15)
result = engine.Tile(params)  # returns bytes

TileParameters ​

  • x int - Tile x coordinate.
  • y int - Tile y coordinate.
  • z int - Tile zoom level.

BaseParameters ​

Shared parameters inherited by Nearest, Table, Route, Match, and Trip.

  • coordinates list[tuple[float, float]] - List of (longitude, latitude) pairs.
  • hints list[str | None] - Base64-encoded hints from previous requests.
  • radiuses list[float | None] - Search radius per coordinate in meters. None for unlimited.
  • bearings list[tuple[int, int] | None] - (bearing, range) pairs in degrees. None for unrestricted.
  • approaches list[str | None] - "curb", "unrestricted", or None.
  • generate_hints bool - Include hints in response. Default: True.
  • exclude list[str] - Road classes to avoid (e.g. ["motorway"]).
  • snapping str - "default" or "any". Default: "default".

Types ​

Coordinate ​

python
coord = osrm.Coordinate((7.41337, 43.72956))
print(coord.lon, coord.lat)

Bearing ​

python
bearing = osrm.Bearing((200, 180))
print(bearing.bearing, bearing.range)

Object / Array ​

Service results are returned as Object (dict-like) and Array (list-like) wrappers around OSRM's internal JSON types. They support [], len(), in, and iteration.

python
result = engine.Route(params)
for route in result["routes"]:
    print(route["distance"], route["duration"])

CLI ​

The package also installs OSRM command-line tools, accessible via python -m osrm:

bash
python -m osrm extract data.osm.pbf -p profiles/car.lua
python -m osrm contract data.osrm
python -m osrm partition data.osrm
python -m osrm customize data.osrm
python -m osrm datastore data.osrm
python -m osrm routed data.osrm