A client for the [Overpass API], a read-only API that serves up custom selected
parts of [OpenStreetMap] data.
The Overpass API is optimized for data consumers that need a few elements within
a glimpse or up to roughly 10 million elements in some minutes, both selected by
search criteria like location, type of objects, tag properties, proximity, or
combinations of them. To make use of it, you should familiarize yourself with
[Overpass QL], the query language used to select the elements that you want.
#### Contents
- [Features](#features)
- [Usage](#usage)
- [Choosing Extras](#choosing-extras)
#### See also
- An overview of modules, classes and functions can be found in the [API reference](http://www.timwie.dev/aio-overpass/)
- The version history is available in [RELEASES.md](https://github.com/timwie/aio-overpass/blob/main/RELEASES.md)
- There are some notebooks to check out in [examples/](https://github.com/timwie/aio-overpass/tree/main/examples)
- Developers can find some instructions in [CONTRIBUTING.md](https://github.com/timwie/aio-overpass/blob/main/CONTRIBUTING.md)
- The Overpass API [repository](https://github.com/drolbr/Overpass-API),
its [blog](https://dev.overpass-api.de/blog/),
its [user's manual](https://dev.overpass-api.de/overpass-doc/en/index.html)
and its [release notes](https://wiki.openstreetmap.org/wiki/Overpass_API/versions)
- [Overpass Turbo] to prototype your queries in your browser
<br>
## Features
- Asynchronous requests using [aiohttp]
- Parallel queries within rate limits
- Fault tolerance through a (customizable) retry strategy
- **Extras**
- Typed elements that simplify browsing result sets
- [Shapely] geometries for manipulation and analysis
- [GeoJSON] exports
- Simplified querying and processing of public transportation routes
### Design Goals
- A small and stable set of core functionality.
- Good defaults for queries and retrying.
- Sensible and spec-compliant GeoJSON exports for all objects that represent spatial features.
- Detailed documentation that supplements learning about OSM and the Overpass API.
- Room for extensions that simplify querying and/or processing of spatial data
in specific problem domains.
<br>
## Usage
There are three basic steps to fetch the spatial data you need:
1. **Formulate a query**
- Either write your own custom query, f.e. `Query("node(5369192667); out;")`,
- or use one of the `Query` subclasses, f.e. `SingleRouteQuery(relation_id=1643324)`.
2. **Call the Overpass API**
- Prepare your client with `client = Client(user_agent=...)`.
- Use `await client.run_query(query)` to fetch the result set.
3. **Collect results**
- Either access the raw result dictionaries with `query.result_set`,
- or use a collector, f.e. `collect_elements(query)` to get a list of typed `Elements`.
- Collectors are often specific to queries - `collect_routes` requires a `RouteQuery`,
for instance.
<br>
### Example: looking up a building in Hamburg
#### a) Results as Dictionaries
You may use the `.result_set` property to get a list of all query results
without any extra processing:
```python
from aio_overpass import Client, Query
query = Query('way["addr:housename"=Elbphilharmonie]; out geom;')
client = Client()
await client.run_query(query)
query.result_set
```
```python
[
{
"type": "way",
"id": 24981342,
# ...
"tags": {
"addr:city": "Hamburg",
"addr:country": "DE",
"addr:housename": "Elbphilharmonie",
# ...
},
}
]
```
<br>
#### b) Results as Objects
This will give you a user-friendly Python interface
for [nodes](https://www.timwie.dev/aio-overpass/aio_overpass/element.html#Node),
[ways](https://www.timwie.dev/aio-overpass/aio_overpass/element.html#Way),
and [relations](https://www.timwie.dev/aio-overpass/aio_overpass/element.html#Relation).
Here we use the `.tags` property:
```python
from aio_overpass.element import collect_elements
elems = collect_elements(query)
elems[0].tags
```
```python
{
"addr:city": "Hamburg",
"addr:country": "DE",
"addr:housename": "Elbphilharmonie",
# ...
}
```
<br>
#### c) Results as GeoJSON
The processed elements can also easily be converted to GeoJSON:
```python
import json
json.dumps(elems[0].geojson, indent=4)
```
```json
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
9.9832434,
53.5415472
],
...
]
]
},
"properties": {
"id": 24981342,
"type": "way",
"tags": {
"addr:city": "Hamburg",
"addr:country": "DE",
"addr:housename": "Elbphilharmonie",
...
},
...
},
"bbox": [
9.9832434,
53.540877,
9.9849674
53.5416212,
]
}
```
<br>
## Choosing Extras
This library can be installed with a number of optional extras.
- Install no extras, if you're fine with `dict` result sets.
- Install the `shapely` extra, if you would like the convenience of typed OSM elements.
It is also useful if you are interested in elements' geometries,
and either already use Shapely, or want a simple way to export [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON).
- This includes the `pt` module to make it easier to interact with public transportation routes.
Something seemingly trivial like listing the stops of a route can have unexpected pitfalls,
since stops can have multiple route members, and may have a range of different tags and roles.
This submodule will clean up the relation data for you.
- Install the `networkx` extra to enable the `pt_ordered` module, if you want a route's path as a
simple line from A to B. It is hard to do this consistently, mainly because ways are not always
ordered, and stop positions might be missing. You can benefit from this submodule if you wish to
- render a route's path between any two stops
- measure the route's travelled distance between any two stops
- validate the order of ways in the relation
- check if the route relation has gaps
- Install the `joblib` extra to speed up `pt_ordered.collect_ordered_routes()`, which can benefit
greatly from parallelization.
[aiohttp]: https://docs.aiohttp.org/en/stable/
[GeoJSON]: https://en.wikipedia.org/wiki/GeoJSON
[OpenStreetMap]: https://www.openstreetmap.org
[Overpass API]: https://wiki.openstreetmap.org/wiki/Overpass_API
[Overpass QL]: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL
[Overpass Turbo]: http://overpass-turbo.eu/
[Shapely]: https://shapely.readthedocs.io/en/latest/manual.html
Raw data
{
"_id": null,
"home_page": "https://github.com/timwie/aio-overpass",
"name": "aio-overpass",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "geojson, geospatial, gis, openstreetmap, osm, overpass-api, public-transport, spatial-analysis, spatial-data, shapely",
"author": "Tim Wiechers",
"author_email": "mail@timwie.dev",
"download_url": "https://files.pythonhosted.org/packages/5d/21/333f87039c6683875e23a6645b6d0bd6662a989a1346f96028ec578c8105/aio_overpass-0.13.1.tar.gz",
"platform": null,
"description": "A client for the [Overpass API], a read-only API that serves up custom selected\nparts of [OpenStreetMap] data.\n\nThe Overpass API is optimized for data consumers that need a few elements within\na glimpse or up to roughly 10 million elements in some minutes, both selected by\nsearch criteria like location, type of objects, tag properties, proximity, or\ncombinations of them. To make use of it, you should familiarize yourself with\n[Overpass QL], the query language used to select the elements that you want.\n\n#### Contents\n- [Features](#features)\n- [Usage](#usage)\n- [Choosing Extras](#choosing-extras)\n\n#### See also\n- An overview of modules, classes and functions can be found in the [API reference](http://www.timwie.dev/aio-overpass/)\n- The version history is available in [RELEASES.md](https://github.com/timwie/aio-overpass/blob/main/RELEASES.md)\n- There are some notebooks to check out in [examples/](https://github.com/timwie/aio-overpass/tree/main/examples)\n- Developers can find some instructions in [CONTRIBUTING.md](https://github.com/timwie/aio-overpass/blob/main/CONTRIBUTING.md)\n- The Overpass API [repository](https://github.com/drolbr/Overpass-API),\n its [blog](https://dev.overpass-api.de/blog/),\n its [user's manual](https://dev.overpass-api.de/overpass-doc/en/index.html)\n and its [release notes](https://wiki.openstreetmap.org/wiki/Overpass_API/versions)\n- [Overpass Turbo] to prototype your queries in your browser\n\n<br>\n\n## Features\n- Asynchronous requests using [aiohttp]\n- Parallel queries within rate limits\n- Fault tolerance through a (customizable) retry strategy\n- **Extras**\n - Typed elements that simplify browsing result sets\n - [Shapely] geometries for manipulation and analysis\n - [GeoJSON] exports\n - Simplified querying and processing of public transportation routes\n\n### Design Goals\n- A small and stable set of core functionality.\n- Good defaults for queries and retrying.\n- Sensible and spec-compliant GeoJSON exports for all objects that represent spatial features.\n- Detailed documentation that supplements learning about OSM and the Overpass API.\n- Room for extensions that simplify querying and/or processing of spatial data\n in specific problem domains.\n\n<br>\n\n## Usage\nThere are three basic steps to fetch the spatial data you need:\n\n1. **Formulate a query**\n - Either write your own custom query, f.e. `Query(\"node(5369192667); out;\")`,\n - or use one of the `Query` subclasses, f.e. `SingleRouteQuery(relation_id=1643324)`.\n\n2. **Call the Overpass API**\n - Prepare your client with `client = Client(user_agent=...)`.\n - Use `await client.run_query(query)` to fetch the result set.\n\n3. **Collect results**\n - Either access the raw result dictionaries with `query.result_set`,\n - or use a collector, f.e. `collect_elements(query)` to get a list of typed `Elements`.\n - Collectors are often specific to queries - `collect_routes` requires a `RouteQuery`,\n for instance.\n\n<br>\n\n### Example: looking up a building in Hamburg\n#### a) Results as Dictionaries\nYou may use the `.result_set` property to get a list of all query results\nwithout any extra processing:\n\n```python\nfrom aio_overpass import Client, Query\n\nquery = Query('way[\"addr:housename\"=Elbphilharmonie]; out geom;')\n\nclient = Client()\n\nawait client.run_query(query)\n\nquery.result_set\n```\n\n```python\n[\n {\n \"type\": \"way\",\n \"id\": 24981342,\n # ...\n \"tags\": {\n \"addr:city\": \"Hamburg\",\n \"addr:country\": \"DE\",\n \"addr:housename\": \"Elbphilharmonie\",\n # ...\n },\n }\n]\n```\n\n<br>\n\n#### b) Results as Objects\nThis will give you a user-friendly Python interface\nfor [nodes](https://www.timwie.dev/aio-overpass/aio_overpass/element.html#Node),\n[ways](https://www.timwie.dev/aio-overpass/aio_overpass/element.html#Way),\nand [relations](https://www.timwie.dev/aio-overpass/aio_overpass/element.html#Relation).\nHere we use the `.tags` property:\n\n```python\nfrom aio_overpass.element import collect_elements\n\nelems = collect_elements(query)\n\nelems[0].tags\n```\n\n```python\n{\n \"addr:city\": \"Hamburg\",\n \"addr:country\": \"DE\",\n \"addr:housename\": \"Elbphilharmonie\",\n # ...\n}\n\n```\n\n<br>\n\n#### c) Results as GeoJSON\nThe processed elements can also easily be converted to GeoJSON:\n\n```python\nimport json\n\njson.dumps(elems[0].geojson, indent=4)\n```\n\n```json\n{\n \"type\": \"Feature\",\n \"geometry\": {\n \"type\": \"Polygon\",\n \"coordinates\": [\n [\n [\n 9.9832434,\n 53.5415472\n ],\n ...\n ]\n ]\n },\n \"properties\": {\n \"id\": 24981342,\n \"type\": \"way\",\n \"tags\": {\n \"addr:city\": \"Hamburg\",\n \"addr:country\": \"DE\",\n \"addr:housename\": \"Elbphilharmonie\",\n ...\n },\n ...\n },\n \"bbox\": [\n 9.9832434,\n 53.540877,\n 9.9849674\n 53.5416212,\n ]\n}\n```\n\n<br>\n\n## Choosing Extras\nThis library can be installed with a number of optional extras.\n\n- Install no extras, if you're fine with `dict` result sets.\n\n- Install the `shapely` extra, if you would like the convenience of typed OSM elements.\n It is also useful if you are interested in elements' geometries,\n and either already use Shapely, or want a simple way to export [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON).\n\n - This includes the `pt` module to make it easier to interact with public transportation routes.\n Something seemingly trivial like listing the stops of a route can have unexpected pitfalls,\n since stops can have multiple route members, and may have a range of different tags and roles.\n This submodule will clean up the relation data for you.\n\n- Install the `networkx` extra to enable the `pt_ordered` module, if you want a route's path as a\n simple line from A to B. It is hard to do this consistently, mainly because ways are not always\n ordered, and stop positions might be missing. You can benefit from this submodule if you wish to\n - render a route's path between any two stops\n - measure the route's travelled distance between any two stops\n - validate the order of ways in the relation\n - check if the route relation has gaps\n\n- Install the `joblib` extra to speed up `pt_ordered.collect_ordered_routes()`, which can benefit\n greatly from parallelization.\n\n[aiohttp]: https://docs.aiohttp.org/en/stable/\n[GeoJSON]: https://en.wikipedia.org/wiki/GeoJSON\n[OpenStreetMap]: https://www.openstreetmap.org\n[Overpass API]: https://wiki.openstreetmap.org/wiki/Overpass_API\n[Overpass QL]: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL\n[Overpass Turbo]: http://overpass-turbo.eu/\n[Shapely]: https://shapely.readthedocs.io/en/latest/manual.html\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Async client for the Overpass API",
"version": "0.13.1",
"project_urls": {
"Documentation": "https://www.timwie.dev/aio-overpass/",
"Homepage": "https://github.com/timwie/aio-overpass",
"Release Notes": "https://github.com/timwie/aio-overpass/blob/main/RELEASES.md",
"Repository": "https://github.com/timwie/aio-overpass",
"Test Coverage": "https://codecov.io/gh/timwie/aio-overpass"
},
"split_keywords": [
"geojson",
" geospatial",
" gis",
" openstreetmap",
" osm",
" overpass-api",
" public-transport",
" spatial-analysis",
" spatial-data",
" shapely"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a566d589f455b796967aca4d60ccf3163570cf270dbc7e56ca87089a2a817fe",
"md5": "2072ecde3e850d34679173d302b96636",
"sha256": "1a1c7ca2aa7e6c59dc9f4ecb9c2366c114b7716a440a91fef5ef3ba973a263db"
},
"downloads": -1,
"filename": "aio_overpass-0.13.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2072ecde3e850d34679173d302b96636",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 57349,
"upload_time": "2024-04-29T23:09:18",
"upload_time_iso_8601": "2024-04-29T23:09:18.800797Z",
"url": "https://files.pythonhosted.org/packages/9a/56/6d589f455b796967aca4d60ccf3163570cf270dbc7e56ca87089a2a817fe/aio_overpass-0.13.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d21333f87039c6683875e23a6645b6d0bd6662a989a1346f96028ec578c8105",
"md5": "9eace9ff40155c8342ccc19593a93df2",
"sha256": "ef62bbc2a1ec0851cd7b63afba7c961baf1799fcafcad6811ec96f238929e301"
},
"downloads": -1,
"filename": "aio_overpass-0.13.1.tar.gz",
"has_sig": false,
"md5_digest": "9eace9ff40155c8342ccc19593a93df2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 54602,
"upload_time": "2024-04-29T23:09:20",
"upload_time_iso_8601": "2024-04-29T23:09:20.310644Z",
"url": "https://files.pythonhosted.org/packages/5d/21/333f87039c6683875e23a6645b6d0bd6662a989a1346f96028ec578c8105/aio_overpass-0.13.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-29 23:09:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "timwie",
"github_project": "aio-overpass",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aio-overpass"
}
JSON
