Routingpy
🌎 Python library to access all public routing, isochrones and matrix APIs in a consistent manner.
Install / Use
/learn @mthh/RoutingpyREADME
routingpy
.. image:: https://github.com/mthh/routingpy/workflows/tests/badge.svg :target: https://github.com/mthh/routingpy/actions/workflows/ci-tests.yml :alt: Test Status
.. image:: https://readthedocs.org/projects/routingpy/badge/?version=latest :target: https://routingpy.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
.. image:: https://coveralls.io/repos/github/mthh/routingpy/badge.svg?branch=master :target: https://coveralls.io/github/mthh/routingpy :alt: Coverage Status
.. image:: https://img.shields.io/pypi/dm/routingpy.svg :target: https://pypi.org/project/routingpy/ :alt: Monthly Downloads
.. image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/mthh/routingpy/master?filepath=examples :alt: MyBinder.org
Project Update (June 2025): A new maintainer has taken over the project as of June 16, 2025. Over the coming weeks, I'll be reviewing the codebase, triaging issues and pull requests, and identifying areas that may need updating. A new release is targeted for November 2025. Stay tuned for updates!
One lib to route them all - routingpy is a Python 3 client for several popular routing webservices.
Inspired by geopy <https://github.com/geopy/geopy>_ and its great community of contributors, routingpy enables
easy and consistent access to third-party spatial webservices to request route directions, isochrones
or time-distance matrices.
routingpy currently includes support for the following services:
Mapbox, OSRM_Openrouteservice_Google Maps_Graphhopper_OpenTripPlannerV2_Local Valhalla_Local OSRM_IGN_
This list is hopefully growing with time and contributions by other developers. An up-to-date list is always available in our documentation_.
routingpy is tested against:
- CPython versions 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14,
- PyPy3 versions 3.9 and 3.10.
© routingpy contributors 2022 under the Apache 2.0 License_.
.. image:: https://user-images.githubusercontent.com/10322094/57357720-e180c080-7173-11e9-97a4-cecb4670065d.jpg :alt: routing-py-image
Why routingpy?
You want to
- get from A to B by transit, foot, bike, car or hgv
- compute a region of reachability
- calculate a time distance matrix for a N x M table
and don't know which provider to use? Great. Then routingpy is exactly what you're looking for.
For the better or worse, every provider works on different spatial global datasets and uses a plethora of algorithms on top. While Google or HERE build on top of proprietary datasets, providers such as Mapbox or Graphhopper consume OpenStreetMap data for their base network. Also, all providers offer a different amount of options one can use to restrict the wayfinding. Ultimately this means that results may differ - and our experience tells us: they do, and not too little. This calls for a careful evaluation which service provider to use for which specific use case.
With routingpy we have made an attempt to simplify this process for you.
Installation
.. image:: https://badge.fury.io/py/routingpy.svg :target: https://badge.fury.io/py/routingpy :alt: PyPI version
Recommended: Install via poetry_:
.. code:: bash
poetry add routingpy
Install using pip with
.. code:: bash
pip install routingpy
Or the lastest from source
.. code:: bash
pip install git+https://github.com/mthh/routingpy.git
API
Every provider has its own specifications and features. However the basic blueprints are the same across all. We tried hard to make the transition from one provider to the other as seamless as possible. We follow two dogmas for all implementations:
-
All basic parameters have to be the same for all routers for each endpoint
-
All routers still retain their special parameters for their endpoints, which make them unique in the end
This naturally means that usually those basic parameters are not named the same way as the endpoints they query. However, all provider specific parameters are named the exact same as their remote counterparts.
The following table gives you an overview which basic arguments are abstracted:
+-----------------------+-------------------+--------------------------------------------------------------+
| Endpoint | Argument | Function |
+=======================+===================+==============================================================+
| directions | locations | | Specify the locations to be visited in order. Usually this |
| | | | is done with [Lon, Lat] tuples, but some routers offer |
| | | | additional options to create a location element. |
| +-------------------+--------------------------------------------------------------+
| | profile | | The mode of transport, i.e. car, bicycle, pedestrian. Each |
| | | | router specifies their own profiles. |
+-----------------------+-------------------+--------------------------------------------------------------+
| isochrones | locations | | Specify the locations to calculate isochrones for. Usually |
| | | | this is done with [Lon, Lat] tuples, but some routers |
| | | | offer additional options to create a location element. |
| +-------------------+--------------------------------------------------------------+
| | profile | | The mode of transport, i.e. car, bicycle, pedestrian. Each |
| | | | router specifies their own profiles. |
| +-------------------+--------------------------------------------------------------+
| | intervals | | The ranges to calculate isochrones for. Either in seconds |
| | | | or in meters, depending on interval_type. |
| +-------------------+--------------------------------------------------------------+
| | intervals _type | | The dimension of intervals, which takes router |
| | | | dependent values, but generally describes time or distance |
+-----------------------+-------------------+--------------------------------------------------------------+
| matrix | locations | | Specify all locations you want to calculate a matrix |
| | | | for. If sources or destinations is not set, this |
| | | | will return a symmetrical matrix. Usually this is done |
| | | | with [Lon, Lat] tuples, but some routers offer |
| | | | additional options to create a location element. |
| +-------------------+--------------------------------------------------------------+
| | profile | | The mode of transport, i.e. car, bicycle, pedestrian. Each |
| | | | router specifies their own profiles. |
| +-------------------+--------------------------------------------------------------+
| | sources | | The indices of the locations parameter iterable to |
| | | | take as sources for the matrix calculation. If not |
| | | | specified all locations are considered to be sources. |
| +-------------------+--------------------------------------------------------------+
| | destinations | | The indices of the locations parameter iterable to |
| | | | take as destinations for the matrix calculation. If not |
| | | | specified all locations are considered to be |
| | | | destinations. |
+-----------------------+-------------------+--------------------------------------------------------------+
Contributing
We :heart: contributions and realistically think that's the only way to support and maintain most
routing engines in the long run. To get you started, we created a Contribution guideline <./CONTRIBUTING.md>_.
Examples
Follow our examples to understand how simple routingpy is to use.
On top of the examples listed below, find interactive notebook(s) on mybinder.org_.
Basic Usage
Get all attributes
++++++++++++++++++
**routingpy** is designed to take the burden off your shoulder to parse the JSON response of each provider, exposing
the most important information of the response as attributes of the response object. The actual JSON is always accessible via
the ``raw`` attribute:
.. code:: python
from routingpy import Valhalla
from pprint import pprint
# Some locations in Berlin
coords = [[13.413706, 52.490202], [13.421838, 52.514105],
[13.453649, 52.507987], [13.401947, 52.543373]]
client = Valhalla()
route = client.directions(locations=coords, profile='pedestrian')
isochrones = client.isochrones(locations=coords[0], profile='pedestrian', intervals=[600, 1200])
matrix = client.matrix(locations=coords, profile='pe
