Querying Data

Contents

Introduction

As we explained in the introduction to rendering rules, Maperitive rules work on features. Maperitive provides a simple query language which is used to to specify what a feature represents. Let's look at one simple example of a feature:

street : way [highway=residential]

Here we defined a feature called street which covers OSM ways tagged as highway=residential. The text after the colon (':') is called a spatial specification:

way [highway=residential]

The above spatial specification in consists of two parts:

Targets

Maperitive currently supports these targets:

Are Targets Necessary?

Good question. They are, and they are not - depending on the situation. You don't need to specify the target - in certain situations Maperitive can figure out by itself what you're actually targeting. An example:

features
	...
	areas
		parking : amenity=parking
	...

is perfectly valid and it should work OK within the rules. This is because you specified the parking feature under the areas subsection, so Maperitive knows that it has to look for closed OSM ways. If, on the other hand, you specified it like this:

features
	...
	parking : amenity=parking
	...

it means that the parking feature can be targeted to any feature type (point, line and area). In this case the feature will cover both OSM parking nodes and OSM parking areas. But it will also target any non-closed OSM way that has mistakenly been specified as amenity=parking. To avoid this, you can also specify it like this:

features
	...
	parking : node[amenity=parking] area[amenity=parking]
	...

As you can see, you can use several spatial specifications for a feature. This way you're telling Maperitive to look both at nodes and areas and the end feature will contain the combination of them.

Spatial Conditions

As their name says, spatial conditions specify what qualities the map elements must satisfy in order to be selected. Typically these qualities are expressed through element tags and their values, for example:

amenity=parking

specifies that we are looking for elements which have a tag called amenity and the value of this tag must be parking in order for the element to be selected.

There are several distinct ways a condition can be specified:

Each of these will now be described.

Key/Value Condition

This is a most common scenario: we want to find elements which have a certain tag and value combination. Examples:

highway=motorway
name="New York"
name:de=Muenchen
"strange key"="strange value"

As you can see from examples, you can enclose both the tag name and the tag value within quotes. This is necessary if the tag name or value contains spaces or some special characters which are otherwise reserved for Maperitive's query language.

Testing The Tag Against Multiple Values

Let's say you're looking for a restaurant, even if fast-food. Instead of writing a condition like

amenity=restaurant OR amenity=fast_food

you can use the isOneOf function to test the tag against multiple values:

@isOneOf(amenity, restaurant, fast_food)

Checking The Existence Of A Tag

If you are only interested in whether a certain tag exists (regardless of its value), you simply specify the tag name, for example:

highway

will match any kind of road in the OSM data.

Numeric Tag Value Comparisons

If a tag value represents a numeric value, you can compare against it using the standard comparison operators: >, >=, < and <=. For example

population >= 100000

will match all elements which have a population larger than 100,000. You can of course specify decimal values too:

width > 2.5

NOTE: If an element's tag value cannot be interpreted as a numeric value, the condition will not be satisfied and the element will not match the condition.

Spatial Condition Functions

Maperitive supports several functions which can be used inside conditions. These functions accept a series of arguments and return result indicating whether the condition was satisfied or not.

@isTrue Function

USAGE: @isTrue (tag name)

This function checks whether the specified tag contains a Boolean true value. Following conventions in the OSM world, the method will return a successful response if the tag has one of the following values:

If the tag does not exist or the value of the tag is not one of the above, the method returns a negative response.

@isFalse function is the exact opposite to the @isTrue function.

EXAMPLES:

@isTrue(oneway)
@istrue(trailblazed)

@isFalse Function

USAGE: @isFalse (tag name)

This function checks whether the specified tag contains a Boolean false value. Following conventions in the OSM world, the method will return a successful response if the tag has one of the following values:

@isTrue function is the exact opposite to the @isFalse function.

EXAMPLES:

@isFalse(oneway)
@isfalse(trailblazed)

@isOneOf Function

USAGE: @isOneOf (tag name, tag value 1, tag value 2, ..., tag value N)

Tests the value of the specified tag against multiple values (specified in function arguments). The function returns a successful response if one of the values is matched. If none of the values matches the tag value, the function returns a negative response.

EXAMPLES:

@isOneOf(highway, motorway, trunk, primary)

@isMatch Function

USAGE: @isMatch (tag name, regular expression)

Tests the value of the specified tag against the specified regular expression. The function returns a successful response if the value matches the regular expression. Otherwise the function returns a negative response.

EXAMPLES:

@isMatch(name, ".*wald$")

matches any element whose name ends with "wald".

@isMulti Function

USAGE: @isMulti (tag name, multiplier numeric value)

Tests whether the specified tag's numeric value is a multiplier of the second argument value. If an element's tag value cannot be interpreted as a numeric value, the function will return a negative response.

EXAMPLES:

@isMulti(elevation, 100)

matches any element whose elevation is a multiplier of 100 (100, 200, 300 etc).

Nested Queries

Maperitive also supports nested queries like

 node[barrier=gate].way[highway=footpath]

This query is made out of two spatial specifications:

 node[barrier=gate]

looks for OSM nodes which represent gate barriers, and

 .way[highway=footpath]

then acts on the results of the first query, so for each of the gate barriers it looks for OSM ways it belongs to and selects only those ways which are tagged as footpaths.

You can do further nesting using the '.' syntax.

NOTE: Nested queries are still work in progress, so expect bugs and things that are not yet implemented.

Find Commands

In addition to specifying features in rules, you can also use the query language to look for things interactively. This is what the find command and find-here command are for. For example, if you type the following command in the command box:

find way[highway=residential AND NOT name]

...Maperitive will look for unnamed residential streets in any OSM file you've loaded into your current map. If it finds any, it will highlight them on the map. You can then go through the results using the find-next (TODO) and find-prev (TODO) commands.

Query Examples

To illustrate the usage and syntax of the querying language, this section lists some examples of queries.

 way[]

Finds all ways.

 node[]

Finds all nodes (be careful with this one on a large OSM area, since there can be a lot of nodes).

area [landuse=forest OR natural=wood]

Finds areas designated as forests.

relation[type=route and route=bicycle and network=icn]

Finds international cycle routes defined as OSM relations.

node[amenity=parking] area[amenity=parking]

Finds parking areas, both those designated by OSM nodes and those designated by OSM areas (closed ways).

contour[elevation_multiplier=50]

Finds contours with the elevation which is a multiplier of 50 (50 m, 100 m, 1000 m etc.).

highway

Finds all OSM ways which have the highway tag (regardless of its value).

NOT highway

Opposite case: finds all OSM ways which do not have the highway tag.

way[highway and not name]

Finds all OSM ways which have the highway tag and do not have the name tag.

 way[highway=footpath].node[barrier=gate]

Finds all OSM nodes which represent a gate barrier and are on the footpaths.

 node[barrier=gate].way[highway=footpath]

Finds all OSM ways which represent footpaths and which have at least one gate barrier on them.

 gpstrack[].gpspoint[]

Finds all points of all GPS tracks.

See also: