Filter

The filter parameter allows to control the OSM data that is conidered in your request.

You can create textual filter strings that combine several properties of an OSM element. These are described in more detail below in the Selectors section.

• OSM tags

• OSM type and OSM id

• OSM changeset id

• geometry type and length / area

Simple filters usually combine OSM tags and geometry type.

"filter": "highway=bus_stop and geometry:point"

"filter": "landuse=forest and geometry:polygon"

"filter": "highway=primary and geometry:line"

More complex filter expressions can be composed out of several actual filters, which are combined with boolean operators and parentheses. These are described in more detail below in the Operators section.

"filter": "(amenity=hospital or healthcare=hospital) and (geometry:polygon or geometry:point)"

Selectors

	description	example
key=value	matches all entities which have this exact tag	natural=tree
key=*	matches all entities which have any tag with the given key	addr:housenumber=*
key!=value	matches all entities which do not have this exact tag	oneway!=yes
key!=*	matches all entities which do not have any tag with the given key	name!=*
key in (value list)	matches all entities which do have any tag with the given key and one of the given values	highway in (residential, living_street)
key ~ prefix* / key ~ *suffix / key ~ *substring**	matches all entities which do have any tag with the given key and a values matching the given prefix, suffix or substring	name ~ *street
type:osm-type	matches all entities of the given osm type	type:node
id:osm-id	matches all entities with the given osm id [1]	id:1234
id:osm-type/osm-id	matches the entity with the given osm type and id	id:node/1234
id:(osm-id list)	matches all entities with the given osm ids [1]	id:(1, 42, 1234)
id:(osm-type/osm-id list)	matches all entities with the given osm types and ids	id:(node/1, way/3)
id:(id range)	matches all entities with an id matching the given id range [2]	id:(1 .. 9999)
geometry:geom-type	matches anything which has a geometry of the given type (point, line, polygon, or collection)	geometry:polygon
area:(from..to)	matches features with a geometry having an area (measured in m²) in the given range [2]	area:(1.0 .. 1E6)
length:(from..to)	matches features with a geometry having a length (measured in m) in the given range [2]	length:( .. 100)
changeset:id	matches contributions [3] performed in the specified changeset	changeset:42
changeset:(id list)	matches contributions [3] performed in one of the specified changesets	changeset:(10, 42)
changeset:(from..to)	matches contributions [3] performed in a range of changesets	changeset:(10..42)

[1] (1,2)

Keep in mind that osm ids are not unique between osm types. In order to include only a specific object the id needs to be used together with an osm type filter. Alternatively, one can also use the combined type+id filter (e.g. id:node/1234).

[2] (1,2,3)

The lower or upper bound of a range may be omitted to indicate that the values are only to be limited to be “up to” or “starting from” the given value, respectively. For example: id:(10..) will accept all entities with an id of 10 or higher.

[3] (1,2,3)

The changeset filters can only be used in contribution based API endpoints.

Operators

	description	example
(…)	can be used to change precedence of operators	highway=primary and (name=* or ref=*)
not X	negates the following filter expression	not type:node
X and Y	returns entities which match both filter expressions X and Y	highway=service and service=driveway
X or Y	returns entities which match at least one of the filter expressions X or Y	natural=wood or landuse=forest

Operators follow the following order of precedence: parentheses before not, before and, before or.

Special Characters & Whitespace

When writing filters, tags without special characters can be supplied directly. There is no need to quote them. Allowed characters are: the letters a-z and A-Z, digits, underscore, dashes and colons.

"filter": "amenity=drinking_water"

"filter": "name:it=*"

When filtering by tags with any other characters in their key or value, these strings need to be supplied as double-quoted strings. Escape sequences can be used to represent a literal double-quote character \", while a literal backslash is written as \\.

"filter": "name=\"Heidelberger Brückenaffe\""

"filter": "opening_hours=\"24/7\""

Whitespace such as spaces, tabs or newlines can be put freely between operators or parts of selectors to make a filter more readable.

"filter": "name = *"

"filter": "(amenity=hospital or healthcare=hospital)\nand\n(geometry:polygon or geometry:point)"

Examples

Here are some useful examples for querying various OSM features:

OSM Feature	filter	comment
forests/woods	(landuse=forest or natural=wood) and geometry:polygon	Using geometry:polygon will select closed ways as well as multipolygons (e.g. a forest with clearings).
parks and park benches	leisure=park and geometry:polygon or amenity=bench and (geometry:point or geometry:line)	A filter can also fetch features of different geometry types: this returns parks (polygons) as well as park benches (points or lines).
buildings	building=* and building!=no and geometry:polygon	This filter also excludes the (rare) objects marked with building=no, which is a tag used to indicate that a feature might be expected to be a building (e.g. from an outdated aerial imagery source), but is in reality not one.
highways	type:way and (highway in (motorway, motorway_link, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, unclassified, residential, living_street, pedestrian) or (highway=service and service=alley))	The list of used tags depends on the exact definition of a “highway”. In a different context, it may also include less or even more tags (footway, cycleway, track, path, all highway=service, etc.)
residential roads missing a name (for quality assurance)	type:way and highway=residential and name!=* and noname!=yes	Note that some roads might be actually unnamed in reality. Such features can be marked as unnamed with the noname tag in OSM.
implausibly large buildings	geometry:polygon and building=* and building!=no and area:(1E6..)	The currently largest building by footprint area is a car factory building measuring about 887,800 m².

Further Information

The filter is expressed as a ANTLR grammar and a Python based parser is used to interpret a given filter. You can find further information in the Readme of the ohsome-filter-to-sql library.