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 |
|
---|---|---|
|
matches all entities which
have this exact tag
|
|
|
matches all entities which have
any tag with the given key
|
|
|
matches all entities
which do not have
this exact tag
|
|
|
matches all entities which do not
have any tag with the given key
|
|
|
matches all entities which do
have any tag with the given key
and one of the given values
|
|
|
matches all entities of the
given osm type
|
|
|
matches all entities with the
given osm id 1
|
|
|
matches the entity with the given
osm type and id
|
|
|
matches all entities with the
given osm ids 1
|
|
|
matches all entities with the
given osm types and ids
|
|
|
matches all entities with an id
matching the given id range 2
|
|
|
matches anything which has a
geometry of the given type
(point, line, polygon, or other)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 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
|
|
|
negates the following filter
expression
|
|
|
returns entities which match
both filter expressions X and Y
|
|
|
returns entities which match at
least one of the filter
expressions X or Y
|
|
Operators follow the following order of precedence: parentheses before not
, before and
, before or
.
Special Characters & Whitespace
amenity=drinking_water
or name:it=*
.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 willselect 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 isa 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 , allhighway=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 tagin 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.