Skip to main content

Simple osm routing engine.

Project description


PyPI GitHub Workflow Status (main) Coveralls github branch PyPI - Python Version PyPI - License

Simple routing engine for OpenStreetMaps with easy to customize profiles/weight-functions.


  • Python 3.6.1 or newer


pip install routor



The CLI offers multiple commands, use routor --help to find out more.

Download map

Downloads a compatible map from OSM, eg.

routor download "Bristol, England" ./bristol.graphml

By default it only adds a handful of tags (nodes, edge) to the graph. Use -n or -e to add other available tags (edge, node) as well. Additionally, you can download multiple regions at once:

routor download -n junction -n traffic_signals -e surface -e lanes "Bristol, England" "Somerset, England" ./bristol_somerset.graphml

By default, each downloaded map is enhanced with

  • street_count - how many physical segments are connected to a node
  • bearing - angle of each edge
  • speed_kph - free-flow travel speed based on maxspeed, fallback is set to 30 kph (see osmnx for more information)
  • travel_time - Travel time based on speed_kph and length

If you provide a Google API (using --api-key), the following additional attributes are available:

  • elevation - elevation above sea level
  • grade/grade_abs - grade of an endge

Calculate route

Determine the optimal route between two points using the given weight function and print the route as JSON to stdout.

routor route -- ./bristol.graphml  "51.47967237816338,-2.6174926757812496" "51.45422084861252,-2.564105987548828" "routor.weights.length"



The configuration is either read from a .env file or the environment. Before you are able to run the server, you have to set the variables mentioned in routor/api/

Run the API

The api is served using uvicorn. To start the server run

uvicorn routor.api.main:app

The API will be available at and the docs at

As library

You can also use the engine as a library. To calculate a route from A to B you can do

from pathlib import Path

from routor.engine import Engine
from routor import models, weights

map_path = Path(...)
engine = Engine(map_path)

origin = models.Location(latitude=51.47967237816338, longitude=-2.6174926757812496)
destination = models.Location(latitude=51.45422084861252, longitude=-2.564105987548828)

route = engine.route(origin, destination, weight_func=weights.length, travel_time_func=weights.travel_time)  # shortest distance

Available weight-functions

"length" / routor.weights.length

Calculates the shortest path from A to B, only the length of an edge is taken into account.

"travel_time" / routor.weight.travel_time

Calculates the fastest route based on travel time.


routor implements a simple plugin mechanism. Simply create a new module with the prefix routor_, make it available (install it, sys.path hack or similar) and it will be automatically discovered and loaded. Depending on how you structure your module/plugin, you have to do the registration of the additional functionality in either routor_YOUR_MODULE/ or

Register a new weight function

Existing weight functions are defined in routor/ and can be taken as reference. To register a new function in your plugin, you have to implement something similar to

from typing import Optional

from routor.weights import register
from routor import models

def my_weight_func(prev_edge: Optional[models.Edge], edge: models.Edge) -> float:
    return ...

register(my_weight_func, "weight_func")


This project uses poetry for packaging and managing all dependencies and pre-commit to run flake8, isort, mypy and black.

Additionally, pdbpp and better-exceptions are installed to provide a better debugging experience. To enable better-exceptions you have to run export BETTER_EXCEPTIONS=1 in your current session/terminal.

Clone this repository and run

poetry install
poetry run pre-commit install

to create a virtual enviroment containing all dependencies. Afterwards, You can run the test suite using

poetry run pytest

This repository follows the Conventional Commits style.

Cookiecutter template

This project was created using cruft and the cookiecutter-pyproject template. In order to update this repository to the latest template version run

cruft update

in the root of this repository.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

routor-0.7.1.tar.gz (14.8 kB view hashes)

Uploaded source

Built Distribution

routor-0.7.1-py3-none-any.whl (15.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page