Repository files navigation

If you are reading this notice on Github, please point your bookmarks and git remotes at theoverpass-python repoon Codeberg instead. This project will not be updated on Github.

OverpassAPI for Python.

pip install overpass

First, create an API object.

importoverpassapi=overpass.API()

The API constructor takes several parameters, all optional:

The default endpoint ishttps://overpass-api.de/api/interpreter butyou can pass in another instance:

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

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

api=overpass.API(timeout=600)

Setting this toTrue will get you debug output.

Most users will only ever need to use theget() 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 theJSON output you would getfrom the Overpass APIdirectly.

Note that the Overpass query passed toget() should not contain anyout or other meta statements. Seeverbosity below for how to control the output.

Another example:

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

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

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

You can set the verbosity of theOverpass queryout 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.

>>>importoverpass>>>api=overpass.API()>>>data=api.get('way(42.819,-73.881,42.820,-73.880);(._;>;)',verbosity='geom')>>> [fforfindata.featuresiff.geometry['type']=="LineString"]

(froma question on GIS Stackexchange)

You can set the response type of your query usingget()'sresponseformat 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 choosecsv, you will need to specify which fields you want, as describedhere 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'],    ....]

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 setbuild toFalse to make the API not do any pre-processing.

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 adate ordatetime object from thedatetime library.

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

This is a shorthand for acomplete ways andrelationsquery in a bounding box (the 'map call'). You just pass the bounding boxto the constructor:

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

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

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

Usingpytest.

py.test

Create anewissue.

The command line tool was deprecated in version 0.4.0.

There are other python modules that do similar things.

• https://github.com/mocnik-science/osm-python-tools
• https://github.com/DinoTools/python-overpy