API Reference

Base classes

class overpassforge.base.Statement(label=None)

Represents a generic Overpass QL statement.

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

class overpassforge.base.Set(filters=[], label=None)

Represents a set, i.e. a statement that always returns a set of elements.

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

out(*options)

Indicate that this set must be outputed.

Parameters:: options (str | tuple[float, float, float, float]) – empty or any combination of “ids”, “skel”, “body”, “tags”, “meta”, “noids”, “geom”, “bb”, “center”, “asc”, “qt”, “count” or a bounding box (south,west,north,east).
Raises:: ValueError – Invalid output options.

filter(*filters)

Adds filters to the set.

Parameters:: filters (Filter | str) – A list of filters or strings representing raw filters.
Return type:: Set

where(*keys, **tags)

Adds filters “key”, ~”key”, “key”=”value”, or “key”~”value”.

Parameters:

keys (str | Regex) – List of keys the elements must have
tags (str | Regex) – List of key=”value” tags the elements must have.

Return type:

Set

within(area)

Filters the elements that are in the specified area.

Parameters:: area (tuple[float, float, float, float] | BoundingBox | Polygon | Area | Areas) – A bounding box (filter object or as a tuple), polygon filter, area filter or set of areas.
Return type:: Set

intersection(*others)

Returns the statement computing the intersection of this statement with the others.

Parameters:: others (Statement) – Other statements to intersect with
Return type:: Set

changed_since(date)

Filters the elements that were changed since the specified datetime.

Parameters:: date (datetime) – The lower bound of change dates to consider
Return type:: Set

changed_between(lower, upper)

Filters the elements that were changed between the two specified dates.

Parameters:

lower (datetime) – Lower bound datetime.
upper (datetime) – Upper bound datetime.

Return type:

Set

last_changed_by(*users)

Filters the elements that last changed by any of the given users.

Parameters:: users (str | int) – The list of user names or user ids.
Return type:: Set

outlines_of(area)

Filters the elements that are part of the outline of the given area.

Parameters:: area (Areas) – The area to consider to outline of.
Return type:: Set

around(radius, other=None, lats=None, lons=None)

Filters elements that are within a given radius of the elements of another set or a list of given coordinates (cannot specify both).

Parameters:

radius (float) – The radius to consider around each element (in meters).
other (Optional[Statement]) – Another statement.
lats (Optional[Iterable[float]]) – List of latitude of points.
lons (Optional[Iterable[float]]) – List of longitudes of points.

Return type:

Set

recursed_down()

Returns the recursed down (>) set.

Return type:: RecurseDown

recursed_down_rels()

Returns the recursed down relations (>>) set.

Return type:: RecurseDownRels

recursed_up()

Returns the recursed down (<) set.

Return type:: RecurseUp

recursed_up_rels()

Returns the recursed up relations (<<) set.

Return type:: RecurseUpRels

overlapping_areas()

Returns the set of areas that overlap at least one of the elements of this set.

Return type:: Areas

elements(*filters)

Returns the elements (nodes, ways, relations) in this set.

Return type:: Elements

nodes(*filters)

Returns the nodes in this set.

Return type:: Nodes

ways(*filters)

Returns the ways in this set.

Return type:: Ways

relations(*filters)

Returns the relations in this set.

Return type:: Relations

areas(*filters)

Returns the areas in this set.

Return type:: Areas

Statements

class overpassforge.statements.RawStatement(raw='', label=None, **dependencies)

Bases: Statement

Represents a raw Overpass query string. It can be formated to support dependency from other statements (raw or not).

Example:

>>> foo = Nodes().where(name="Foo")
>>> bar = Statement("node.{x}[amenity=\"bar\"]->.{:out_var};", x=foo)
>>> baz = Nodes(input_set=bar).within((50.6,7.0,50.8,7.3))
>>> print(build(baz))
node["name"="Foo"]->.set_0;
node.set_0[amenity="bar"]->.set_1;
node.set_1(50.6,7.0,50.8,7.3);

Parameters:

raw (str) – A formatable string of the query. Named placeholders (e.g. “{name}”) indicating dependency on other statements. An optional special {:out_var} placeholder indicates where the name of the output set must be placed.
dependencies (Statement) – The list of statements whose results it depends on Their keyword names must match the placeholders in the raw query string.

Raises:

ValueError – Invalid unamed placholder “{}”.

class overpassforge.statements.Elements(ids=None, label=None, *, bounding_box=None, input_set=None, within=None, around=None, filters=[], **tags)

Bases: Set

Represents a query set, e.g. node, rel, way…

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

class overpassforge.statements.Nodes(ids=None, label=None, *, bounding_box=None, input_set=None, within=None, around=None, filters=[], **tags)

Bases: Elements

A node query.

Example:

>>> all_nodes = Nodes(bounding_box=(50.6,7.0,50.8,7.3))
>>> cinemas = all_nodes.where(amenity="cinema")
>>> non_cinemas = all_nodes - cinemas
>>> print(build(non_cinemas))
node(50.6,7.0,50.8,7.3)->.set_0;
(.set_0; - node.set_0["amenity"="cinema"];);

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

class overpassforge.statements.Ways(ids=None, label=None, *, bounding_box=None, input_set=None, within=None, around=None, filters=[], **tags)

Bases: Elements

A way query.

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

class overpassforge.statements.Relations(ids=None, label=None, *, bounding_box=None, input_set=None, within=None, around=None, filters=[], **tags)

Bases: Elements

A relation query.

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

class overpassforge.statements.Areas(ids=None, label=None, *, bounding_box=None, input_set=None, within=None, around=None, filters=[], **tags)

Bases: Elements

An area query.

Parameters:: label (Optional[str]) – A label for this statement which may be used as variable name for the result of this statement at compilation.

elements_within(*filters)

Returns the elements within the areas.

Return type:: Elements

nodes_within(*filters)

Returns the nodes within the areas.

Return type:: Nodes

ways_within(*filters)

Returns the ways within the areas.

Return type:: Ways

relations_within(*filters)

Returns the relations within the areas.

Return type:: Relations

outline()

Returns the elements that are part of the outline of the areas.

Return type:: Elements

class overpassforge.statements.Union(*statements, label=None)

Bases: Combination

Represents a union of sets: (set_1; set_2; …);

Example:

>>> union = Union(Ways(42), Nodes(42))
>>> print(build(union))
(way(42); node(42));
>>> union = Ways(42) + Nodes(42)
>>> print(build(union))
(way(42); node(42));

Parameters:: statements (Set) – The list of statement whose results to combine.

class overpassforge.statements.Difference(a, b, label=None)

Bases: Combination

Represents the difference of two sets: (set_1 - set_2;);

Example:

>>> bbox_ways = Ways(bounding_box=(50.6,7.0,50.8,7.3))
>>> one_way = Ways(41)
>>> print(build(Difference(bbox_ways, one_way)))
(way(50.6,7.0,50.8,7.3); - way(42););
>>> print(build(bbox_ways - one_way))
(way(50.6,7.0,50.8,7.3); - way(42););

Parameters:

a (Statement) – The base statement.
b (Statement) – The statement whose results to remove from a.

class overpassforge.statements.RecurseDown(input_set, label=None)

Bases: _Recurse

Recurse down elements (>). Takes an input set and produces a set composed of: - all nodes that are part of a way which appears in the input set; plus - all nodes and ways that are members of a relation which appears in the input set; plus - all nodes that are part of a way which appears in the result set.