.. Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented. https://diataxis.fr/ 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. .. code-block:: json "filter": "highway=bus_stop and geometry:point" .. code-block:: json "filter": "landuse=forest and geometry:polygon" .. code-block:: json "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. .. code-block:: json "filter": "(amenity=hospital or healthcare=hospital) and (geometry:polygon or geometry:point)" Selectors ^^^^^^^^^ .. table:: :widths: 24 50 24 +------------------------------------+------------------------------------+-----------------------------------+ | | **description** | **example** | +====================================+====================================+===================================+ | ``key=value`` | matches all entities which | ``natural=tree`` | | | have this exact tag | | +------------------------------------+------------------------------------+-----------------------------------+ | ``key=*`` | matches all entities which have | ``addr:housenumber=*`` | | | any tag with the given key | | +------------------------------------+------------------------------------+-----------------------------------+ | ``key!=value`` | matches all entities | ``oneway!=yes`` | | | which do not have | | | | this exact tag | | +------------------------------------+------------------------------------+-----------------------------------+ | ``key!=*`` | matches all entities which do not | ``name!=*`` | | | have any tag with the given key | | +------------------------------------+------------------------------------+-----------------------------------+ | ``key in (value list)`` | matches all entities which do | ``highway in`` | | | have any tag with the given key | ``(residential, | | | and one of the given values | living_street)`` | +------------------------------------+------------------------------------+-----------------------------------+ | ``key ~ prefix*`` / | matches all entities which do | ``name ~ *street`` | | ``key ~ *suffix`` / | have any tag with the given key | | | ``key ~ *substring**`` | and a values matching the given | | | | prefix, suffix or substring | | +------------------------------------+------------------------------------+-----------------------------------+ | ``type:osm-type`` | matches all entities of the | ``type:node`` | | | given osm type | | +------------------------------------+------------------------------------+-----------------------------------+ | ``id:osm-id`` | matches all entities with the | ``id:1234`` | | | given osm id [1]_ | | +------------------------------------+------------------------------------+-----------------------------------+ | ``id:osm-type/osm-id`` | matches the entity with the given | ``id:node/1234`` | | | osm type and id | | +------------------------------------+------------------------------------+-----------------------------------+ | ``id:(osm-id list)`` | matches all entities with the | ``id:(1, 42, 1234)`` | | | given osm ids [1]_ | | +------------------------------------+------------------------------------+-----------------------------------+ | ``id:(osm-type/osm-id list)`` | matches all entities with the | ``id:(node/1, way/3)`` | | | given osm types and ids | | +------------------------------------+------------------------------------+-----------------------------------+ | ``id:(id range)`` | matches all entities with an id | ``id:(1 .. 9999)`` | | | matching the given id range [2]_ | | +------------------------------------+------------------------------------+-----------------------------------+ | ``geometry:geom-type`` | matches anything which has a | ``geometry:polygon`` | | | geometry of the given type | | | | (point, line, polygon, or | | | | collection) | | +------------------------------------+------------------------------------+-----------------------------------+ | ``area:(from..to)`` | matches features with a geometry | ``area:(1.0 .. 1E6)`` | | | having an area (measured in m²) | | | | in the given range [2]_ | | +------------------------------------+------------------------------------+-----------------------------------+ | ``length:(from..to)`` | matches features with a geometry | ``length:( .. 100)`` | | | having a length (measured in m) | | | | in the given range [2]_ | | +------------------------------------+------------------------------------+-----------------------------------+ | ``changeset:id`` | matches contributions [3]_ | ``changeset:42`` | | | performed in the specified | | | | changeset | | +------------------------------------+------------------------------------+-----------------------------------+ | ``changeset:(id list)`` | matches contributions [3]_ | ``changeset:(10, 42)`` | | | performed in one of the | | | | specified changesets | | +------------------------------------+------------------------------------+-----------------------------------+ | ``changeset:(from..to)`` | matches contributions [3]_ | ``changeset:(10..42)`` | | | performed in a range of | | | | changesets | | +------------------------------------+------------------------------------+-----------------------------------+ .. [1] 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] 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] The `changeset` filters can only be used in `contribution` based API endpoints. | Operators ^^^^^^^^^ .. table:: :widths: 24 50 24 +------------------------+------------------------------------+------------------------+ | | **description** | **example** | +========================+====================================+========================+ | ``(…)`` | can be used to change | ``highway=primary and | | | precedence of operators | (name=* or ref=*)`` | +------------------------+------------------------------------+------------------------+ | ``not X`` | negates the following filter | ``not type:node`` | | | expression | | +------------------------+------------------------------------+------------------------+ | ``X and Y`` | returns entities which match | ``highway=service and | | | both filter expressions X and Y | service=driveway`` | +------------------------+------------------------------------+------------------------+ | ``X or Y`` | returns entities which match at | ``natural=wood or | | | least one of the filter | landuse=forest`` | | | expressions X or Y | | +------------------------+------------------------------------+------------------------+ 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. .. code-block:: json "filter": "amenity=drinking_water" .. code-block:: json "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 ``\\``. .. code-block:: json "filter": "name=\"Heidelberger Brückenaffe\"" .. code-block:: json "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. .. code-block:: json "filter": "name = *" .. code-block:: json "filter": "(amenity=hospital or healthcare=hospital)\nand\n(geometry:polygon or geometry:point)" Examples ^^^^^^^^^ Here are some useful examples for querying various OSM features: .. table:: :widths: 24 34 34 +------------------+--------------------------------------------------------+------------------------------+ | **OSM Feature** | **filter** | **comment** | +==================+========================================================+==============================+ | forests/woods | | ``(landuse=forest or natural=wood) and`` | Using | | | | ``geometry:polygon`` | ``geometry:polygon`` will | | | | select closed ways as | | | | well as multipolygons | | | | (e.g. a forest with | | | | clearings). | +------------------+--------------------------------------------------------+------------------------------+ | parks and | | ``leisure=park and geometry:polygon or`` | A filter can also fetch | | park benches | | ``amenity=bench and (geometry:point or`` | features of different | | | | ``geometry:line)`` | geometry types: this | | | | returns parks | | | | (polygons) as well as | | | | park benches (points or | | | | lines). | +------------------+--------------------------------------------------------+------------------------------+ | buildings | | ``building=* and building!=no and`` | This filter also | | | | ``geometry:polygon`` | 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,`` | The list of used tags | | | | ``motorway_link, trunk, trunk_link,`` | depends on the exact | | | | ``primary, primary_link, secondary,`` | definition of a | | | | ``secondary_link, tertiary,`` | "highway". In a | | | | ``tertiary_link, unclassified,`` | different context, it may | | | | ``residential, living_street, pedestrian)`` | also include less or even | | | | ``or (highway=service and service=alley))`` | more tags | | | | (``footway``, ``cycleway``, | | | | ``track``, ``path``, all | | | | ``highway=service``, etc.) | +------------------+--------------------------------------------------------+------------------------------+ | residential | | ``type:way and highway=residential and`` | Note that some roads | | roads missing | | ``name!=* and noname!=yes`` | might be actually | | a name (for | | unnamed in reality. | | quality | | Such features can be | | assurance) | | marked as unnamed | | | | with the ``noname`` tag | | | | in OSM. | +------------------+--------------------------------------------------------+------------------------------+ | implausibly | | ``geometry:polygon and building=* and`` | The currently largest | | large | | ``building!=no and area:(1E6..)`` | building by footprint area | | buildings | | 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 `_.