.. image:: https://github.com/GIScience/openrouteservice-py/workflows/tests/badge.svg :target: https://github.com/GIScience/openrouteservice-py/actions :alt: Build status

.. image:: https://codecov.io/gh/GIScience/openrouteservice-py/branch/master/graph/badge.svg?token=QqGC8XfCiI :target: https://codecov.io/gh/GIScience/openrouteservice-py :alt: Codecov coverage

.. image:: https://readthedocs.org/projects/openrouteservice-py/badge/?version=latest :target: http://openrouteservice-py.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. image:: https://badge.fury.io/py/openrouteservice.svg :target: https://badge.fury.io/py/openrouteservice :alt: PyPI version

.. image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/GIScience/openrouteservice-py/master?filepath=examples%2Fbasic_example.ipynb :alt: MyBinder

Quickstart

Description

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: https://openrouteservice.org .. _homepage: https://openrouteservice.org .. _ORS API documentation: https://openrouteservice.org/documentation/ .. _openrouteservice-py documentation: http://openrouteservice-py.readthedocs.io/en/latest/ .. _directions: https://openrouteservice.org/documentation/#/reference/directions/directions/directions-service .. _Pelias geocoding: https://github.com/pelias/documentation/blob/master/search.md#available-search-parameters .. _Pelias reverse geocoding: https://github.com/pelias/documentation/blob/master/reverse.md#reverse-geocoding-parameters .. _Pelias structured geocoding: https://github.com/pelias/documentation/blob/master/structured-geocoding.md .. _Pelias autocomplete: https://github.com/pelias/documentation/blob/master/autocomplete.md .. _isochrones: https://openrouteservice.org/documentation/#/reference/isochrones/isochrones/isochrones-service .. _elevation: https://github.com/GIScience/openelevationservice/ .. _reverse geocoding: https://openrouteservice.org/documentation/#/reference/geocoding/geocoding/geocoding-service .. _matrix routing calculations: https://openrouteservice.org/documentation/#/reference/matrix/matrix/matrix-service-(post) .. _places: https://github.com/GIScience/openpoiservice .. _Optimization: https://github.com/VROOM-Project/vroom/blob/master/docs/API.md .. _here: https://github.com/GIScience/openrouteservice-examples/tree/master/python .. _terms and conditions: https://openrouteservice.org/terms-of-service/ .. _forum: https://ask.openrouteservice.org/c/sdks

Requirements

openrouteservice-py is tested against Python 3.6, 3.7, 3.8 and 3.9, and PyPy3.6 and PyPy3.7.

For setting up a testing environment, install poetry first.

For Linux and osx::

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

For windows::

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

Then create a venv and install the dependencies with poetry::

python -m venv .venv && source .venv/bin/activate
poetry install -vv

Installation

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@development

Testing

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

pytest -v

-v flag for verbose output (recommended).

Usage

For an interactive Jupyter notebook have a look on mybinder.org <https://mybinder.org/v2/gh/GIScience/openrouteservice-py/master?filepath=examples%2Fbasic_example.ipynb>_.

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)

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

.. 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 <https://en.wikipedia.org/wiki/Travelling_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)

print(routes)

Decode Polyline ^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, the directions API returns encoded polylines <https://developers.google.com/maps/documentation/utilities/polylinealgorithm>_. 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)

print(decoded)

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(
  url='/new_url',
  post_json={
      'coordinates': coords,
      'profile': 'driving-car',
      'format': 'geojson'
  })

Support

For general support and questions, contact our forum_.

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

.. _forum: https://ask.openrouteservice.org/c/sdks

Acknowledgements

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

.. _googlemaps: https://github.com/googlemaps/google-maps-services-python