query

Prints all features that match the given query to stdout, in a variety of formats.

Usage:

gol query [<options>] <gol-file> <query>

The query must be written in GOQL, the Geo-Object Query Language. GOQL is similar to MapCSS, which is used by Mapnik and Overpass to select OSM objects.

For example:

gol query geodata/france 
  na[amenity=fire_station], n[emergency=fire_hydrant]
  -b=2.2,48.8,2.5,48.9 -f=geojson 
  -u=https://www.mywebsite.com/myfeatures/france -n

retrieves all fire stations (which can be nodes or areas) and hydrants (which only exist as nodes) from the france.gol library (stored in the geodata folder). The features must lie fully or partially inside the specified bounding box (a rectangle that covers metropolitan Paris) and are printed to stdout as GeoJSON (see below).

Tiles that are part of the query area, but that are not already present in the library, are downloaded from the specified URL. If the library itself does not yet exist, it is created (option -n, or --new).

• The path of the library is resolved relative to the current directory. The .gol file extension may be omitted.

Options

-a, --area=<FILE>

Defines the area to which the command should be applied. Currently, only polygon files are supported.

-b, --bbox=<W>,<S>,<E>,<N>

Defines the rectangular area (bounding box) to which the command should be applied. Coordinates are specified in WGS-84 (degrees longitude and latitude) and take the form <west>,<south>,<east>,<north>. Coordinates must not be separated by spaces (otherwise, they would be interpreted as separate arguments).

As an alternative, this option accepts a tile descriptor in the form z/x/y.

-f, --format=<TYPE>

The output format of the results:

OSM-XML output is not suitable for editing, since the IDs for untagged nodes won’t match the original OSM data (You can open these XML files in JOSM, but please don’t upload them).

-f:<OPTION>, --format:<OPTION> = <VALUE>

Formatting options to customize the output. These are primarily used by map and stats. Common options are documented below:

-f:id=<STYLE> 0.2

Defines the style of IDs used for csv, geojson/geojsonl, list and table:

Keep in mind:

• OSM IDs are only unique within each OSM type (This means there could be a node and way that share the same ID).
• To avoid ID collisions, use a plain $id only if you are querying n or w or r.
• Areas (a) can consist of both way and relation features, so the OSM type must be incorporated into the ID.

-f:max-width=<NUMBER>

The maximum width (in characters) of the displayed table (used by stats and table. Default: 100

-f:sort=<KEYS>|id 0.2

Specifies the sort order of results. By default, results are returned in no particular order.

Sorting may substantially increase memory consumption (and decrease performance), especially for large result sets (millions of features).

-l, --limit=<NUMBER>

The maximum number of features to be displayed or counted.

-t, --tags=<LIST>

A comma-separated list of OSM keys, which determine the feature tags to be included in the output.

There are several special keys that only apply to the csv output option and produce additional columns:

If --tags is omitted, all tags are included in the output.

--tags is ignored if the requested output format is count or list.

-n, --new

Use this option to create an empty .gol file if the specified library does not exist (rather than failing with an error message). Combine this option with --url to specify a tile repository from which the library will be populated.

--precision=0-15

The coordinate precision (digits after the decimal point) to use.

Applies only to csv, geojson/geojsonl, poly and xml.

-u, --url=<URL>

Specifies the URL of the remote repository from which tiles are downloaded into the library.

Solutions to Common Problems

Be aware that > and | have special meanings for the shell (re-directing/piping of the output stream), so if your query contains these characters, you will need to enclose it in quotes.

This won’t work:

gol query germany w[highway][maxspeed>100]  

Instead, write:

gol query germany "w[highway][maxspeed>100]"

To write the output of your query to a file:

gol query germany "w[highway][maxspeed>100]" -f:csv > fast-roads.csv

Also, be aware that the shell doesn’t play nicely with quotation marks (which are required if literal values in the query contain spaces or punctuation).

This won’t work:

gol query uk na[amenity=pub][name="The Howling Hound"]

The shell “eats” the double quotes instead of passing it to the GOL utility, which then reports an error. To avoid this problem, use single quotes:

gol query uk na[amenity=pub][name='The Howling Hound']

If the query string itself contains quotation characters, prefix them with a backslash (\):

gol query uk na[amenity=pub][name='King\'s Crossing']

gol query uk na[amenity=pub][name='The \"Happy\" Place']