.. image:: https://github.com/GIScience/openrouteservice-py/workflows/tests/badge.svg
:target: https://github.com/GIScience/openrouteservice-py/actions
:alt: Build status
.. image:: https://coveralls.io/repos/github/GIScience/openrouteservice-py/badge.svg?branch=master
:target: https://coveralls.io/github/GIScience/openrouteservice-py?branch=master
:alt: Coveralls 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://github.com/GIScience/openrouteservice-py/workflows/Conda%20Package/badge.svg?branch=master
:target: https://anaconda.org/MichaelsJP/openrouteservice
:alt: Conda Build
.. image:: https://anaconda.org/michaelsjp/openrouteservice/badges/version.svg
:target: https://anaconda.org/MichaelsJP/openrouteservice
:alt: Conda 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 CPython 3.7, 3.8 and 3.9, and PyPy3.
For setting up a testing environment, install ``requirements-dev.txt``::
pip install -r requirements-dev.txt
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::
nosetests -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
Raw data
{
"_id": null,
"home_page": "https://github.com/GIScience/openrouteservice-py",
"name": "openrouteservice",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "routing accessibility router OSM ORS openrouteservice openstreetmap isochrone POI elevation DEM",
"author": "Nils Nolde",
"author_email": "nils.nolde@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c7/c2/2a9784750f244d6f2ae982f7e2862383af4c6d8d9e9ca793603500d04d16/openrouteservice-2.3.3.tar.gz",
"platform": "",
"description": ".. image:: https://github.com/GIScience/openrouteservice-py/workflows/tests/badge.svg\n :target: https://github.com/GIScience/openrouteservice-py/actions\n :alt: Build status\n\n.. image:: https://coveralls.io/repos/github/GIScience/openrouteservice-py/badge.svg?branch=master\n :target: https://coveralls.io/github/GIScience/openrouteservice-py?branch=master\n :alt: Coveralls coverage\n\n.. image:: https://readthedocs.org/projects/openrouteservice-py/badge/?version=latest\n :target: http://openrouteservice-py.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://badge.fury.io/py/openrouteservice.svg\n :target: https://badge.fury.io/py/openrouteservice\n :alt: PyPI version\n\n.. image:: https://github.com/GIScience/openrouteservice-py/workflows/Conda%20Package/badge.svg?branch=master\n :target: https://anaconda.org/MichaelsJP/openrouteservice\n :alt: Conda Build\n\n.. image:: https://anaconda.org/michaelsjp/openrouteservice/badges/version.svg\n :target: https://anaconda.org/MichaelsJP/openrouteservice\n :alt: Conda Version\n\n.. image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/GIScience/openrouteservice-py/master?filepath=examples%2Fbasic_example.ipynb\n :alt: MyBinder\n\nQuickstart\n==================================================\n\nDescription\n--------------------------------------------------\nThe openrouteservice library gives you painless access to the openrouteservice_ (ORS) routing API's.\nIt performs requests against our API's for\n\n- directions_\n- isochrones_\n- `matrix routing calculations`_\n- places_\n- elevation_\n- `Pelias geocoding`_\n- `Pelias reverse geocoding`_\n- `Pelias structured geocoding`_\n- `Pelias autocomplete`_\n- Optimization_\n\nFor further details, please visit:\n\n- homepage_\n- `ORS API documentation`_\n- `openrouteservice-py documentation`_\n\nWe also have a repo with a few useful examples here_.\n\nFor support, please ask our forum_.\n\nBy using this library, you agree to the ORS `terms and conditions`_.\n\n.. _openrouteservice: https://openrouteservice.org\n.. _homepage: https://openrouteservice.org\n.. _`ORS API documentation`: https://openrouteservice.org/documentation/\n.. _`openrouteservice-py documentation`: http://openrouteservice-py.readthedocs.io/en/latest/\n.. _directions: https://openrouteservice.org/documentation/#/reference/directions/directions/directions-service\n.. _`Pelias geocoding`: https://github.com/pelias/documentation/blob/master/search.md#available-search-parameters\n.. _`Pelias reverse geocoding`: https://github.com/pelias/documentation/blob/master/reverse.md#reverse-geocoding-parameters\n.. _`Pelias structured geocoding`: https://github.com/pelias/documentation/blob/master/structured-geocoding.md\n.. _`Pelias autocomplete`: https://github.com/pelias/documentation/blob/master/autocomplete.md\n.. _isochrones: https://openrouteservice.org/documentation/#/reference/isochrones/isochrones/isochrones-service\n.. _elevation: https://github.com/GIScience/openelevationservice/\n.. _`reverse geocoding`: https://openrouteservice.org/documentation/#/reference/geocoding/geocoding/geocoding-service\n.. _`matrix routing calculations`: https://openrouteservice.org/documentation/#/reference/matrix/matrix/matrix-service-(post)\n.. _places: https://github.com/GIScience/openpoiservice\n.. _Optimization: https://github.com/VROOM-Project/vroom/blob/master/docs/API.md\n.. _here: https://github.com/GIScience/openrouteservice-examples/tree/master/python\n.. _`terms and conditions`: https://openrouteservice.org/terms-of-service/\n.. _forum: https://ask.openrouteservice.org/c/sdks\n\nRequirements\n-----------------------------\nopenrouteservice-py is tested against CPython 3.7, 3.8 and 3.9, and PyPy3.\n\nFor setting up a testing environment, install ``requirements-dev.txt``::\n\n pip install -r requirements-dev.txt\n\nInstallation\n------------------------------\nTo install from PyPI, simply use pip::\n\n\tpip install openrouteservice\n\nTo install the latest and greatest from source::\n\n \tpip install git+git://github.com/GIScience/openrouteservice-py@development\n\n\n\nTesting\n---------------------------------\nIf you want to run the unit tests, see Requirements_. ``cd`` to the library directory and run::\n\n\tnosetests -v\n\n``-v`` flag for verbose output (recommended).\n\n\nUsage\n---------------------------------\n\nFor an interactive Jupyter notebook have a look on `mybinder.org <https://mybinder.org/v2/gh/GIScience/openrouteservice-py/master?filepath=examples%2Fbasic_example.ipynb>`_.\n\nBasic example\n^^^^^^^^^^^^^^^^^^^^\n.. code:: python\n\n\timport openrouteservice\n\n\tcoords = ((8.34234,48.23424),(8.34423,48.26424))\n\n\tclient = openrouteservice.Client(key='') # Specify your personal API key\n\troutes = client.directions(coords)\n\n\tprint(routes)\n\nFor convenience, all request performing module methods are wrapped inside the ``client`` class. This has the\ndisadvantage, that your IDE can't auto-show all positional and optional arguments for the\ndifferent methods. And there are a lot!\n\nThe slightly more verbose alternative, preserving your IDE's smart functions, is\n\n.. code:: python\n\n import openrouteservice\n from openrouteservice.directions import directions\n\n\tcoords = ((8.34234,48.23424),(8.34423,48.26424))\n\n\tclient = openrouteservice.Client(key='') # Specify your personal API key\n\troutes = directions(client, coords) # Now it shows you all arguments for .directions\n\nOptimize route\n^^^^^^^^^^^^^^^^^^^^^^^^^^\nIf you want to optimize the order of multiple waypoints in a simple `Traveling Salesman Problem <https://en.wikipedia.org/wiki/Travelling_salesman_problem>`_,\nyou can pass a ``optimize_waypoints`` parameter:\n\n.. code:: python\n\n\timport openrouteservice\n\n\tcoords = ((8.34234,48.23424),(8.34423,48.26424), (8.34523,48.24424), (8.41423,48.21424))\n\n\tclient = openrouteservice.Client(key='') # Specify your personal API key\n\troutes = client.directions(coords, profile='cycling-regular', optimize_waypoints=True)\n\n\tprint(routes)\n\nDecode Polyline\n^^^^^^^^^^^^^^^^^^^^^^^^^^\nBy default, the directions API returns `encoded polylines <https://developers.google.com/maps/documentation/utilities/polylinealgorithm>`_.\nTo decode to a ``dict``, which is a GeoJSON geometry object, simply do\n\n.. code:: python\n\n import openrouteservice\n from openrouteservice import convert\n\n coords = ((8.34234,48.23424),(8.34423,48.26424))\n\n client = openrouteservice.Client(key='') # Specify your personal API key\n\n # decode_polyline needs the geometry only\n geometry = client.directions(coords)['routes'][0]['geometry']\n\n decoded = convert.decode_polyline(geometry)\n\n print(decoded)\n\nDry run\n^^^^^^^^^^^^^^^^^^^^\nAlthough errors in query creation should be handled quite decently, you can do a dry run to print the request and its parameters:\n\n.. code:: python\n\n import openrouteservice\n\n coords = ((8.34234,48.23424),(8.34423,48.26424))\n\n client = openrouteservice.Client()\n client.directions(coords, dry_run='true')\n\nLocal ORS instance\n^^^^^^^^^^^^^^^^^^^^\nIf you're hosting your own ORS instance, you can alter the ``base_url`` parameter to fit your own:\n\n.. code:: python\n\n import openrouteservice\n\n coords = ((8.34234,48.23424),(8.34423,48.26424))\n\n # key can be omitted for local host\n client = openrouteservice.Client(base_url='http://localhost/ors')\n\n # Only works if you didn't change the ORS endpoints manually\n routes = client.directions(coords)\n\n # If you did change the ORS endpoints for some reason\n # you'll have to pass url and required parameters explicitly:\n routes = client.request(\n url='/new_url',\n post_json={\n 'coordinates': coords,\n 'profile': 'driving-car',\n 'format': 'geojson'\n })\n\nSupport\n--------\n\nFor general support and questions, contact our forum_.\n\nFor issues/bugs/enhancement suggestions, please use https://github.com/GIScience/openrouteservice-py/issues.\n\n\n.. _forum: https://ask.openrouteservice.org/c/sdks\n\n\nAcknowledgements\n-----------------\n\nThis library is based on the very elegant codebase from googlemaps_.\n\n\n.. _googlemaps: https://github.com/googlemaps/google-maps-services-python\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python client for requests to openrouteservice API services",
"version": "2.3.3",
"project_urls": {
"Homepage": "https://github.com/GIScience/openrouteservice-py"
},
"split_keywords": [
"routing",
"accessibility",
"router",
"osm",
"ors",
"openrouteservice",
"openstreetmap",
"isochrone",
"poi",
"elevation",
"dem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "671ae6944e4cfd7c5386b15e4b4056084b3c8c676aca0a215d8b507a6cbc1263",
"md5": "f5875cd1f7fae8460ed7ea3a8735fbbf",
"sha256": "a84fe298b1de7a4fb1d8aa19798687f4f66fe212e5206667c703ca2c7e5de0ce"
},
"downloads": -1,
"filename": "openrouteservice-2.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5875cd1f7fae8460ed7ea3a8735fbbf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 33749,
"upload_time": "2021-02-02T19:26:39",
"upload_time_iso_8601": "2021-02-02T19:26:39.676047Z",
"url": "https://files.pythonhosted.org/packages/67/1a/e6944e4cfd7c5386b15e4b4056084b3c8c676aca0a215d8b507a6cbc1263/openrouteservice-2.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7c22a9784750f244d6f2ae982f7e2862383af4c6d8d9e9ca793603500d04d16",
"md5": "f71e701ddb940b2f60500e4304c28c4e",
"sha256": "3696e0428533cf6bbcb9586c3bcfca7b5e7aaa269650ff16a862a7f61b857f4a"
},
"downloads": -1,
"filename": "openrouteservice-2.3.3.tar.gz",
"has_sig": false,
"md5_digest": "f71e701ddb940b2f60500e4304c28c4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 29130,
"upload_time": "2021-02-02T19:26:40",
"upload_time_iso_8601": "2021-02-02T19:26:40.918526Z",
"url": "https://files.pythonhosted.org/packages/c7/c2/2a9784750f244d6f2ae982f7e2862383af4c6d8d9e9ca793603500d04d16/openrouteservice-2.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-02-02 19:26:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GIScience",
"github_project": "openrouteservice-py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "openrouteservice"
}
JSON
