krafpy / overpass-forge

A library for generating OpenStreetMap's Overpass QL queries from Python objects.

Overpass Forge: a query builder for the Overpass query language

An object-oriented model to build Overpass queries in Python. Primarly intended to generate complex queries in Python. Checkout the documentation.

Install

Requires Python 3.10 or higher. Install with:

pip install overpassforge

Example

from overpassforge import Areas, Nodes, Ways, build, beautify

# Find both cinema nodes and ways in Bonn, which
# are at most 100m away from bus stop nodes

bus_stops = Nodes(within=Areas(name="Bonn"), highway="bus_stop")
ways = Ways(around=(bus_stops, 100.0)).where(amenity="cinema")
nodes = Nodes(around=(bus_stops, 100.0)).where(amenity="cinema")
result = ways + nodes
result.out("meta")

query = build(result)
print(beautify(query))

Output:

area["name"="Bonn"]->.set_0;
node(area.set_0)["highway"="bus_stop"]->.set_1;
(
  way(around.set_1:100.0)["amenity"="cinema"];
  node(around.set_1:100.0)["amenity"="cinema"];
);
out meta;

Features

List of currently implemented features, based on the Overpass QL wiki.

• Settings: all except augmented-difference between dates (adiff)
• Block statements
  • union, difference, intersection
  • For-each loop (foreach)
  • Block statements if, for, complete, retro, compare
• Standalone statements
  • out
  • Item (implicit)
  • Recurse up (<) and down (>)
  • Recurse up relations (<<) and down (>>)
  • Query for areas (is_in)
  • Statements timeline, local, convert, make
  • The Query Statement (node, way, rel, area only)
  • The Query Filter
  • Map way/relation to area (map_to_area)
• Filters
  • By tag (has-kv)
  • Bounding box
  • Recurse (n, w, r, bn, bw, br)
  • Recurse (way_cnt, way_link)
  • By input set (.setname)
  • By element id
  • Relative to other elements (around)
  • By polygon (poly)
  • newer
  • By date of change (changed)
  • By user (user, uid)
  • By area (area)
  • Area pivot (pivot)
  • Conditional query filter (if:)

Contributing

Setup the development environment

Windows

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Linux

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Unit tests

Run all the tests with:

python -m pytest ./tests