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:
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-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
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
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).
For an interactive Jupyter notebook have a look on mybinder.org.
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 .directionsIf you want to optimize the order of multiple waypoints in a simple Traveling Salesman Problem,
you can pass a optimize_waypoints parameter:
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)By default, the directions API returns encoded polylines.
To decode to a dict, which is a GeoJSON geometry object, 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()
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(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'
})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.