openrouteservice

:snake: The Python API to consume openrouteservice(s) painlessly!

https://github.com/giscience/openrouteservice-py

Keywords

Repository

:snake: The Python API to consume openrouteservice(s) painlessly!

README.rst

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

Owner

GitHub Events

Committers

Last synced: 11 months ago

Issues and Pull Requests

Last synced: 9 months ago

Packages