Awesome Open Source
Awesome Open Source

.. image:: :target: :alt: Build status

.. image:: :target: :alt: Coveralls coverage

.. image:: :target: :alt: Documentation Status

.. image:: :target: :alt: PyPI version

.. image:: :target: :alt: Conda Build

.. image:: :target: :alt: Conda Version

.. image:: :target: :alt: MyBinder



The openrouteservice library gives you painless access to the openrouteservice_ (ORS) routing API's. It performs requests against our API's for

  • directions_
  • isochrones_
  • matrix routing calculations_
  • places_
  • elevation_
  • Pelias geocoding_
  • Pelias reverse geocoding_
  • Pelias structured geocoding_
  • Pelias autocomplete_
  • Optimization_

For further details, please visit:

  • homepage_
  • ORS API documentation_
  • openrouteservice-py documentation_

We also have a repo with a few useful examples here_.

For support, please ask our forum_.

By using this library, you agree to the ORS terms and conditions_.

.. _openrouteservice: .. _homepage: .. _ORS API documentation: .. _openrouteservice-py documentation: .. _directions: .. _Pelias geocoding: .. _Pelias reverse geocoding: .. _Pelias structured geocoding: .. _Pelias autocomplete: .. _isochrones: .. _elevation: .. _reverse geocoding: .. _matrix routing calculations: .. _places: .. _Optimization: .. _here: .. _terms and conditions: .. _forum:


openrouteservice-py is tested against CPython 3.7, 3.8 and 3.9, and PyPy3.

For setting up a testing environment, install requirements-dev.txt::

pip install -r requirements-dev.txt


To install from PyPI, simply use pip::

pip install openrouteservice

To install the latest and greatest from source::

pip install git+git://[email protected]


If you want to run the unit tests, see Requirements_. cd to the library directory and run::

nosetests -v

-v flag for verbose output (recommended).


For an interactive Jupyter notebook have a look on <>_.

Basic example ^^^^^^^^^^^^^^^^^^^^ .. code:: python

import openrouteservice

coords = ((8.34234,48.23424),(8.34423,48.26424))

client = openrouteservice.Client(key='') # Specify your personal API key
routes = client.directions(coords)


For convenience, all request performing module methods are wrapped inside the client class. This has the disadvantage, that your IDE can't auto-show all positional and optional arguments for the different methods. And there are a lot!

The slightly more verbose alternative, preserving your IDE's smart functions, is

.. code:: python

import openrouteservice
from openrouteservice.directions import directions

coords = ((8.34234,48.23424),(8.34423,48.26424))

client = openrouteservice.Client(key='') # Specify your personal API key
routes = directions(client, coords) # Now it shows you all arguments for .directions

Optimize route ^^^^^^^^^^^^^^^^^^^^^^^^^^ If you want to optimize the order of multiple waypoints in a simple Traveling Salesman Problem <>_, you can pass a optimize_waypoints parameter:

.. code:: python

import openrouteservice

coords = ((8.34234,48.23424),(8.34423,48.26424), (8.34523,48.24424), (8.41423,48.21424))

client = openrouteservice.Client(key='') # Specify your personal API key
routes = client.directions(coords, profile='cycling-regular', optimize_waypoints=True)


Decode Polyline ^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, the directions API returns encoded polylines <>_. To decode to a dict, which is a GeoJSON geometry object, simply do

.. code:: python

import openrouteservice
from openrouteservice import convert

coords = ((8.34234,48.23424),(8.34423,48.26424))

client = openrouteservice.Client(key='') # Specify your personal API key

# decode_polyline needs the geometry only
geometry = client.directions(coords)['routes'][0]['geometry']

decoded = convert.decode_polyline(geometry)


Dry run ^^^^^^^^^^^^^^^^^^^^ Although errors in query creation should be handled quite decently, you can do a dry run to print the request and its parameters:

.. code:: python

import openrouteservice

coords = ((8.34234,48.23424),(8.34423,48.26424))

client = openrouteservice.Client()
client.directions(coords, dry_run='true')

Local ORS instance ^^^^^^^^^^^^^^^^^^^^ If you're hosting your own ORS instance, you can alter the base_url parameter to fit your own:

.. code:: python

import openrouteservice

coords = ((8.34234,48.23424),(8.34423,48.26424))

# key can be omitted for local host
client = openrouteservice.Client(base_url='http://localhost/ors')

# Only works if you didn't change the ORS endpoints manually
routes = client.directions(coords)

# If you did change the ORS endpoints for some reason
# you'll have to pass url and required parameters explicitly:
routes = client.request(
      'coordinates': coords,
      'profile': 'driving-car',
      'format': 'geojson'


For general support and questions, contact our forum_.

For issues/bugs/enhancement suggestions, please use

.. _forum:


This library is based on the very elegant codebase from googlemaps_.

.. _googlemaps:

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (53,337
api (1,687