Skip to main content

A Python interface to the OpenStreetMap Overpass API

Project description

Overpass API python wrapper

Python bindings for the OpenStreetMap Overpass API.

Install it

pip install overpass

Usage

API() constructor

First, create an API object.

import overpass
api = overpass.API()

The API constructor takes several parameters, all optional:

endpoint

The default endpoint is https://overpass-api.de/api/interpreter but you can pass in another instance:

api = overpass.API(endpoint="https://overpass.myserver/interpreter")

timeout

The default timeout is 25 seconds, but you can set it to whatever you want.

api = overpass.API(timeout=600)

debug

Setting this to True will get you debug output.

Getting data from Overpass: get()

Most users will only ever need to use the get() method. There are some convenience query methods for common queries as well, see below.

response = api.get('node["name"="Salt Lake City"]')

response will be a dictionary representing the JSON output you would get from the Overpass API directly.

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.

Another example:

>>> print [(
...     feature['properties']['name'],
...     feature['id']) for feature in response["features"]]
[(u'Salt Lake City', 150935219), (u'Salt Lake City', 585370637)]

You can find more examples in the examples/ directory of this repository.

The get() method takes a few parameters, all optional having sensible defaults.

verbosity

You can set the verbosity of the Overpass query out directive 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.

>>> import overpass
>>> api = overpass.API()
>>> data = api.get('way(42.819,-73.881,42.820,-73.880);(._;>;)', verbosity='geom')
>>> [f for f in data.features  if f.geometry['type'] == "LineString"]

(from a question on GIS Stackexchange)

responseformat

You 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).

response = api.get('node["name"="Salt Lake City"]', responseformat="xml")

If you choose csv, you will need to specify which fields you want, as described here in the Overpass QL documentation. An example:

response = api.get('node["name"="Springfield"]["place"]', responseformat="csv(name,::lon,::lat)")

The response will be a list of lists:

[
    ['name', '@lon', '@lat'],
    ['Springfield', '-3.0645656', '56.2952787'],
    ['Springfield', '0.4937446', '51.7487585'],
    ['Springfield', '-2.4194716', '53.5732892'],
    ['Springfield', '25.5454526', '-33.9814866'],
    ....
]

build

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

date

You 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). You can also directly pass a date or datetime object from the datetime library.

Pre-cooked Queries: MapQuery, WayQuery

In addition to just sending your query and parse the result, overpass provides shortcuts for often used map queries. To use them, just pass them like to normal query to the API.

MapQuery

This is a shorthand for a complete ways and relations query in a bounding box (the 'map call'). You just pass the bounding box to the constructor:

MapQuery = overpass.MapQuery(50.746,7.154,50.748,7.157)
response = api.get(MapQuery)

WayQuery

This is shorthand for getting a set of ways and their child nodes that satisfy certain criteria. Pass the criteria as a Overpass QL stub to the constructor:

WayQuery = overpass.WayQuery('[name="Highway 51"]')
response = api.get(WayQuery)

Testing

Using pytest.

py.test

FAQ

I need help or have an idea for a feature

Create a new issue.

Where did the CLI tool go?

The command line tool was deprecated in version 0.4.0.

See also

There are other python modules that do similar things.

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

overpass-0.7.2.tar.gz (11.2 kB view details)

Uploaded Source

Built Distribution

overpass-0.7.2-py3-none-any.whl (13.2 kB view details)

Uploaded Python 3

File details

Details for the file overpass-0.7.2.tar.gz.

File metadata

  • Download URL: overpass-0.7.2.tar.gz
  • Upload date:
  • Size: 11.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.11.9 Darwin/23.5.0

File hashes

Hashes for overpass-0.7.2.tar.gz
Algorithm Hash digest
SHA256 2658b3a4b4e30b38314daaf3076202d96b102b66f19a616ba8fd045ce6445c2f
MD5 99fcb975a400fb226762eff951344407
BLAKE2b-256 a564186d0a2e5f76e5f5c767c9ac09a8b69b68a30b59637697766aa7b179a19d

See more details on using hashes here.

File details

Details for the file overpass-0.7.2-py3-none-any.whl.

File metadata

  • Download URL: overpass-0.7.2-py3-none-any.whl
  • Upload date:
  • Size: 13.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.11.9 Darwin/23.5.0

File hashes

Hashes for overpass-0.7.2-py3-none-any.whl
Algorithm Hash digest
SHA256 0b97a31123290425c37c04f2c6cc4b497b730c1977449392448f5f1ce959ad96
MD5 c39fcea136dd4697e96f015b73bc6ca8
BLAKE2b-256 ce3133eb3a90e736a9dfebc8d0fdb39b87b5fc094ed9ab9031ac33ed78ce018f

See more details on using hashes here.

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