Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/GIScience/openrouteservice-py
:snake: The Python API to consume openrouteservice(s) painlessly!
https://github.com/GIScience/openrouteservice-py
api directions-api geocoding-api isochrones python routing-engine
Last synced: 3 months ago
JSON representation
:snake: The Python API to consume openrouteservice(s) painlessly!
- Host: GitHub
- URL: https://github.com/GIScience/openrouteservice-py
- Owner: GIScience
- License: apache-2.0
- Created: 2018-02-02T11:36:56.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-07-18T13:08:41.000Z (4 months ago)
- Last Synced: 2024-07-18T16:15:58.639Z (4 months ago)
- Topics: api, directions-api, geocoding-api, isochrones, python, routing-engine
- Language: Python
- Homepage: https://openrouteservice.org
- Size: 1.67 MB
- Stars: 379
- Watchers: 14
- Forks: 52
- Open Issues: 10
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
README
.. 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 `_.
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 `_,
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 `_.
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