Geo-Object Query Language (GOQL)

GOQL is a concise syntax for describing queries in terms of feature type and tags. It is similar to MapCSS, which in turn is modeled after the original CSS (the Cascading Style Sheets used with HTML).

A query is composed of one or more selectors, which work like their CSS counterparts — but instead of elements and their attributes, they filter features based on their type and tags.

Type must be one or more of the following:

Type identifiers can be combined. For example, na selects both nodes and areas — this is the most common combo, as points-of-interest in OSM are often represented as points or polygons.

To select all element types, use the wildcard *.

To further constrain features, add one or more tag clauses, which function like CSS attribute selectors:

na[amenity=restaurant]

The above selects all nodes and areas that have an amenity tag whose value is restaurant. If multiple tag clauses are specified, the feature must fulfill all of them. For example, this query finds all sushi restaurants that offer takeaway and have a website:

na[amenity=restaurant][cusine=sushi][takeaway][website]

Tag clauses may appear in any order.

A unary tag clause tests for presence of a tag (whose value must not be no). Prepend it with ! to negate it. For example, to find residential streets that are not one-way:

w[highway=residential][!oneway]

Strings that contain characters other than letters, numbers or underscores must be quoted (matching single or double quotes):

na[amenity=pub][name="The King's Head"]

For partial string matches, use the wildcard *:

na[name=The*]       /* "The Best", "Theater"       */
na[name="The *"]    /* "The Best"                  */
na[name=*land]      /* "bland", "New Zealand"      */
na[name=*eat*]      /* "eatery", "Beat", "Theater" */

String matching is always case-sensitive.

For more sophisticated string matching, use regular expressions (using the operator ~ or !~):

na[name~".[Ee]at."]

TODO: more RegEx examples

A query can contain multiple selectors, separated by commas:

na[amenity=restaurant], na[amenity=pub], na[amenity=cafe]

The above can be simplified by specifying multiple values in a single tag clause:

na[amenity=restaurant,pub,cafe]

Quick Reference