{"id":13857112,"url":"https://github.com/GIScience/openrouteservice-py","last_synced_at":"2025-07-13T20:30:34.667Z","repository":{"id":29005901,"uuid":"119974379","full_name":"GIScience/openrouteservice-py","owner":"GIScience","description":":snake: The Python API to consume openrouteservice(s) painlessly!","archived":false,"fork":false,"pushed_at":"2025-02-05T11:32:56.000Z","size":1772,"stargazers_count":425,"open_issues_count":12,"forks_count":62,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-06-09T13:40:58.462Z","etag":null,"topics":["api","directions-api","geocoding-api","isochrones","python","routing-engine"],"latest_commit_sha":null,"homepage":"https://openrouteservice.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GIScience.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-02T11:36:56.000Z","updated_at":"2025-06-08T17:46:47.000Z","dependencies_parsed_at":"2024-02-19T17:05:16.115Z","dependency_job_id":"00ef6318-901a-4e26-9c91-79cefea80bb9","html_url":"https://github.com/GIScience/openrouteservice-py","commit_stats":{"total_commits":205,"total_committers":14,"mean_commits":"14.642857142857142","dds":0.697560975609756,"last_synced_commit":"9fc22f378db8f9ef98a1675031055b1ae2bec97b"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/GIScience/openrouteservice-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GIScience","download_url":"https://codeload.github.com/GIScience/openrouteservice-py/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GIScience%2Fopenrouteservice-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265199604,"owners_count":23726683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","directions-api","geocoding-api","isochrones","python","routing-engine"],"created_at":"2024-08-05T03:01:26.198Z","updated_at":"2025-07-13T20:30:34.634Z","avatar_url":"https://github.com/GIScience.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":".. 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://codecov.io/gh/GIScience/openrouteservice-py/branch/master/graph/badge.svg?token=QqGC8XfCiI\n    :target: https://codecov.io/gh/GIScience/openrouteservice-py\n    :alt: Codecov 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://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 Python 3.6, 3.7, 3.8 and 3.9, and PyPy3.6 and PyPy3.7.\n\nFor setting up a testing environment, install **poetry** first.\n\nFor Linux and osx::\n\n\tcurl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -\n\nFor windows::\n\n    (Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -\n\nThen create a venv and install the dependencies with poetry::\n\n    python -m venv .venv \u0026\u0026 source .venv/bin/activate\n    poetry install -vv\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\tpytest -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 \u003chttps://mybinder.org/v2/gh/GIScience/openrouteservice-py/master?filepath=examples%2Fbasic_example.ipynb\u003e`_.\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 \u003chttps://en.wikipedia.org/wiki/Travelling_salesman_problem\u003e`_,\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 \u003chttps://developers.google.com/maps/documentation/utilities/polylinealgorithm\u003e`_.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGIScience%2Fopenrouteservice-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGIScience%2Fopenrouteservice-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGIScience%2Fopenrouteservice-py/lists"}