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!=*

type:osm-type

matches all entities of the
given osm type

type:node

geometry:geom-type

matches anything which has a
geometry of the given type
(point, line, polygon, or other)

geometry:polygon


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=motorway or
highway=motorway_link or highway=trunk or
highway=trunk_link or highway=primary or
highway=primary_link or highway=secondary or
highway=secondary_link or highway=tertiary or
highway=tertiary_link or highway=unclassified or
highway=residential or highway=living_street or
highway=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
(highway=footway,
highway=cycleway,
highway=track,
highway=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.

Further Information

The filter parameter is powered by a separate Java module, which can be used independently as a maven library. You can further find the open source code, as well as the corresponding Javadoc documentation.