Filter

The filter parameter combines the following: definition of the OSM type, the geometry (simple feature) type, as well as the OSM tag. The filter syntax is defined in textual form. A filter expression can be composed out of several actual filters, which are combined with boolean operators and parentheses.

Note

Please note that you cannot combine the filter parameter with the deprecated types, keys and values parameters.


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)

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 other)

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)

perimeter:(from..to)

matches features with a perimeter (measured in m) in the given range [2]

perimeter:( .. 100)

geometry.vertices:(from..to)

matches features by the number of points they consists of in the given range [2]

geometry.vertices:(1 .. 10)

geometry.outers:number or geometry.outers:(from..to)

matches features by the number of outer rings they consists of in the given range [2]

geometry.outers:1 or geometry.outers:(2 .. )

geometry.inners:number or geometry.inners:(from..to)

matches features by the number of holes (inner rings) they consists of in the given range [2]

geometry.inners:0 or geometry.inners:(1 .. )

geometry.roundness:(from..to)

matches features which have a roundness (or compactness) in the given range [2] [4]

geometry.roundness:(0.8 .. )

geometry.squareness:(from..to)

matches features which have a squareness in the given range [2] [5]

geometry.squareness:(0.8 .. )

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)


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, without needing to quote them. Example: amenity=drinking_water or name:it=*.
Allowed characters are: the letters a-z and A-Z, digits, underscore, dashes and colons. When filtering by tags with any other characters in their key or value, these strings need to be supplied as double-quoted strings, e.g. name="Heidelberger Brückenaffe" or opening_hours="24/7". Escape sequences can be used to represent a literal double-quote character \", while a literal backslash is written as \\.

Whitespace such as spaces, tabs or newlines can be put freely between operators or parts of selectors (name = * is equivalent to name=*) to make a filter more readable.


Examples

Here’s some useful examples for querying some 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 parameter is powered by a separate Java module, which can be used independently as a maven library. You can find further information in the Readme of the *oshdb-filter* module.