Skip to main content

Async client for the Overpass API

Project description

aio-overpass

GitHub Workflow Status codecov PyPI version PyPI - Python Version

A client for the Overpass API, a read-only API that serves up custom selected parts of OpenStreetMap data. It 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

See also

  • An overview of modules, classes and functions can be found in the API reference.
  • The version history is available in CHANGELOG.md.
  • Contributor guide is forthcoming :construction:

Features

  • Asynchronous requests using aiohttp
  • Concurrent queries
  • Respects rate limits
  • Fault tolerance through (customizable) retries
  • Extensions
    • Typed elements that simplify browsing result sets
    • Shapely geometries for manipulation and analysis
    • GeoJSON exports
    • Simplified querying and processing of public transportation routes

Getting Started

pip install aio-overpass
pip install aio-overpass[shapely, networkx, joblib]

poetry add aio-overpass
poetry add aio-overpass[shapely, networkx, joblib]

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

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


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

Example

Results as Dictionaries

from aio_overpass import Client, Query

query = Query("way(24981342); out geom;")

client = Client()

await client.run_query(query)

query.result_set
{
    # ...
    "elements": [
        {
            "type": "way",
            "id": 24981342,
            # ...
            "tags": {
                "addr:city": "Hamburg",
                "addr:country": "DE",
                "addr:housename": "Elbphilharmonie",
                # ...
            },
        }
    ],
}

Results as Objects

from aio_overpass.element import collect_elements

elems = collect_elements(query)

elems[0].tags
{
    "addr:city": "Hamburg",
    "addr:country": "DE",
    "addr:housename": "Elbphilharmonie",
    # ...
}

Results as GeoJSON

import json

json.dumps(elems[0].geojson, indent=4)
{
    "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,
    ]
}

Motivation

Goals

  • A small and stable set of core functionality.
  • Good defaults for queries and retrying.
  • Room for extensions that simplify querying and/or processing of spatial data in specific problem domains.
  • Sensible and spec-compliant GeoJSON exports for all objects that represent spatial features.
  • Detailed documentation that supplements learning about OSM and the Overpass API.

Non-Goals

  • Any sort of Python interface to replace writing Overpass QL code.
  • Integrating other OSM-related services (like the OSM API or Nominatim)
  • Command line interface

Related Projects


License

Distributed under the MIT License. See LICENSE for more information.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aio_overpass-0.1.2.tar.gz (40.4 kB view hashes)

Uploaded Source

Built Distribution

aio_overpass-0.1.2-py3-none-any.whl (41.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page