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

• directions
• Pelias geocoding
• Pelias reverse geocoding
• isochrones
• matrix routing calculations
• places

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 requires:

• Python >= 2.7, 3.4, 3.5, 3.6
• requests library

unit testing requires additionally the following Python libraries:

• nose
• responses
• mock

To install from PyPI, simply use pip:

pip install openrouteservice

To install the latest and greatest from source:

pip install git+git://github.com/GIScience/openrouteservice-py

For conda users, you can install using setuptools (required Python package):

git clone https://github.com/GIScience/openrouteservice-py
python setup.py install

This comman group will install the library to your global environment. Also works in virtual environments.

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).

import openrouteservice

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

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

print routes

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

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

By default, the directions API returns encoded polylines. To decode to a dict, which is GeoJSON-ready, simply do

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)

print decoded

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

import openrouteservice

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

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

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

import openrouteservice

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

# key can be omitted for local host
client = openrouteservice.Client(key='',
                                 base_url='https://foo/bar')

# url is the extension for your endpoint, no trailing slashes!
# params has to be passed explicitly, refer to API reference for details
routes = client.request(url='/directions',
                        params={'coordinates': coords,
                                'profile': 'driving-hgv'
                               }
                        )

For general support and questions, contact our forum.

For issues/bugs/enhancement suggestions, please use https://github.com/GIScience/openrouteservice-py/issues.

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