{"id":13481847,"url":"https://github.com/mvexel/overpass-api-python-wrapper","last_synced_at":"2025-05-14T13:09:40.605Z","repository":{"id":749845,"uuid":"23285415","full_name":"mvexel/overpass-api-python-wrapper","owner":"mvexel","description":"Python bindings for the OpenStreetMap Overpass API","archived":false,"fork":false,"pushed_at":"2025-01-13T18:34:12.000Z","size":2426,"stargazers_count":386,"open_issues_count":21,"forks_count":91,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-11T18:21:33.332Z","etag":null,"topics":["openstreetmap","overpass-api"],"latest_commit_sha":null,"homepage":"","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/mvexel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mvexel"],"patreon":"mvexel","liberapay":"mvexel"}},"created_at":"2014-08-24T16:04:10.000Z","updated_at":"2025-04-02T13:40:33.000Z","dependencies_parsed_at":"2024-02-13T18:03:57.269Z","dependency_job_id":"53dda40d-8fed-4e4c-aef2-59221f4d744f","html_url":"https://github.com/mvexel/overpass-api-python-wrapper","commit_stats":{"total_commits":166,"total_committers":26,"mean_commits":6.384615384615385,"dds":0.4879518072289156,"last_synced_commit":"b50c67972ae85315bc0a6815c72ab1ab9f4cb6c1"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvexel%2Foverpass-api-python-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvexel%2Foverpass-api-python-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvexel%2Foverpass-api-python-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mvexel%2Foverpass-api-python-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mvexel","download_url":"https://codeload.github.com/mvexel/overpass-api-python-wrapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149977,"owners_count":22022852,"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":["openstreetmap","overpass-api"],"created_at":"2024-07-31T17:00:56.641Z","updated_at":"2025-05-14T13:09:35.583Z","avatar_url":"https://github.com/mvexel.png","language":"Python","funding_links":["https://github.com/sponsors/mvexel","https://patreon.com/mvexel","https://liberapay.com/mvexel"],"categories":["Tools","Python","Command line tools (Overpass Turbo and Overpass API)","Libraries"],"sub_categories":["Python"],"readme":"Overpass API python wrapper\n===========================\n\n![GitHub branch check runs](https://img.shields.io/github/check-runs/mvexel/overpass-api-python-wrapper/main)\n![PyPI - Version](https://img.shields.io/pypi/v/overpass)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/overpass)\n![PyPI - License](https://img.shields.io/pypi/l/overpass)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/overpass)\n![GitHub License](https://img.shields.io/github/license/mvexel/overpass-api-python-wrapper)\n![Mastodon Follow](https://img.shields.io/mastodon/follow/17500?domain=https%3A%2F%2Fen.osm.town)\n\n\nPython bindings for the OpenStreetMap [Overpass\nAPI](http://wiki.openstreetmap.org/wiki/Overpass_API).\n\n![shell recording](assets/overpass-demo.gif)\n\nInstall it\n==========\n\n`pip install overpass`\n\n## Usage\n\n### `API()` constructor\n\nFirst, create an API object.\n\n```python\nimport overpass\napi = overpass.API()\n```\n\nThe API constructor takes several parameters, all optional:\n\n#### `endpoint`\n\nThe default endpoint is `https://overpass-api.de/api/interpreter` but\nyou can pass in another instance:\n\n```python\napi = overpass.API(endpoint=\"https://overpass.myserver/interpreter\")\n```\n\n#### `timeout`\n\nThe default timeout is 25 seconds, but you can set it to whatever you\nwant.\n\n```python\napi = overpass.API(timeout=600)\n```\n\n#### `debug`\n\nSetting this to `True` will get you debug output.\n\n### Getting data from Overpass: `get()`\n\nMost users will only ever need to use the `get()` method. There are some convenience query methods for common queries as well, see below.\n\n```python\nresponse = api.get('node[\"name\"=\"Salt Lake City\"]')\n```\n\n`response` will be a dictionary representing the\nJSON output you would get [from the Overpass API\ndirectly](https://overpass-api.de/output_formats.html#json).\n\n**Note that the Overpass query passed to `get()` should not contain any `out` or other meta statements.** See `verbosity` below for how to control the output.\n\nAnother example:\n\n```python\n\u003e\u003e\u003e print [(\n...     feature['properties']['name'],\n...     feature['id']) for feature in response[\"features\"]]\n[(u'Salt Lake City', 150935219), (u'Salt Lake City', 585370637)]\n```\n\nYou can find more examples in the `examples/` directory of this repository.\n\nThe `get()` method takes a few parameters, all optional having sensible defaults.\n\n#### `verbosity`\n\nYou can set the verbosity of the [Overpass query `out` directive](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#out) using the same keywords Overpass does. In order of increased verbosity: `ids`, `skel`, `body`, `tags`, `meta`. As is the case with the Overpass API itself, `body` is the default.\n\n```python\n\u003e\u003e\u003e import overpass\n\u003e\u003e\u003e api = overpass.API()\n\u003e\u003e\u003e data = api.get('way(42.819,-73.881,42.820,-73.880);(._;\u003e;)', verbosity='geom')\n\u003e\u003e\u003e [f for f in data.features  if f.geometry['type'] == \"LineString\"]\n```\n\n(from [a question on GIS Stackexchange](https://gis.stackexchange.com/questions/294152/getting-all-information-about-ways-from-python-overpass-library/294358#294358))\n\n#### `responseformat`\n\nYou can set the response type of your query using `get()`'s `responseformat` parameter to GeoJSON (`geojson`, the default), plain JSON (`json`), CSV (`csv`), and OSM XML (`xml`).\n\n```python\nresponse = api.get('node[\"name\"=\"Salt Lake City\"]', responseformat=\"xml\")\n```\n\nIf you choose `csv`, you will need to specify which fields you want, as described [here](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#CSV_output_mode) in the Overpass QL documentation. An example:\n\n```python\nresponse = api.get('node[\"name\"=\"Springfield\"][\"place\"]', responseformat=\"csv(name,::lon,::lat)\")\n```\n\nThe response will be a list of lists:\n\n```python\n[\n    ['name', '@lon', '@lat'],\n    ['Springfield', '-3.0645656', '56.2952787'],\n    ['Springfield', '0.4937446', '51.7487585'],\n    ['Springfield', '-2.4194716', '53.5732892'],\n    ['Springfield', '25.5454526', '-33.9814866'],\n    ....\n]\n```\n\n#### `build`\n\nWe will construct a valid Overpass QL query from the parameters you set by default. This means you don't have to include 'meta' statements like `[out:json]`, `[timeout:60]`, `[out body]`, etcetera. You just supply the meat of the query, the part that actually tells Overpass what to query for. If for whatever reason you want to override this and supply a full, valid Overpass QL query, you can set `build` to `False` to make the API not do any pre-processing.\n\n#### `date`\n\nYou can query the data as it was on a given date. You can give either a standard ISO date alone (YYYY-MM-DD) or a full overpass date and time (YYYY-MM-DDTHH:MM:SSZ, i.e. 2020-04-28T00:00:00Z).\nYou can also directly pass a `date` or `datetime` object from the `datetime` library.\n\n### Pre-cooked Queries: `MapQuery`, `WayQuery`\n\nIn addition to just sending your query and parse the result, `overpass`\nprovides shortcuts for often used map queries. To use them, just pass\nthem like to normal query to the API.\n\n#### MapQuery\n\nThis is a shorthand for a [complete ways and\nrelations](https://wiki.openstreetmap.org/wiki/Overpass_API/Language_Guide#Recursing_up_and_down:_Completed_ways_and_relations)\nquery in a bounding box (the 'map call'). You just pass the bounding box\nto the constructor:\n\n```python\nMapQuery = overpass.MapQuery(50.746,7.154,50.748,7.157)\nresponse = api.get(MapQuery)\n```\n\n#### WayQuery\n\nThis is shorthand for getting a set of ways and their child nodes that\nsatisfy certain criteria. Pass the criteria as a Overpass QL stub to the\nconstructor:\n\n```python\nWayQuery = overpass.WayQuery('[name=\"Highway 51\"]')\nresponse = api.get(WayQuery)\n```\n\n## Testing\n\nUsing `pytest`.\n\n`py.test`\n\n## FAQ\n\n### I need help or have an idea for a feature\n\nCreate a [new\nissue](https://github.com/mvexel/overpass-api-python-wrapper/issues).\n\n### Where did the CLI tool go?\n\nThe command line tool was deprecated in version 0.4.0.\n\n## See also\n\nThere are other python modules that do similar things.\n\n* https://github.com/mocnik-science/osm-python-tools\n* https://github.com/DinoTools/python-overpy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmvexel%2Foverpass-api-python-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmvexel%2Foverpass-api-python-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmvexel%2Foverpass-api-python-wrapper/lists"}