GOL Tool

From OpenStreetMap Wiki
Jump to navigation Jump to search
GOL Tool
v · d 
Author: GeoDesk Team
License: GNU AGPL v3 (free of charge)
Platforms: Windows, macOS, and Linux
Version: 2.0
Language:
English
Website: https://docs.geodesk.com/gol
Source code: https://github.com/clarisma/geodesk-gol

Command-line utility for building, managing and querying Geo-Object Libraries

Features
Feature Value
Map Display
?
Routing
?
Navigating
?
Tracking
?
Monitoring
?
Editing
Add POIs
?
Edit / Delete POIs
?
Add way
?
Edit geometries
?
Edit arbitrary tags of existing OSM objects
?
Edit relations
?
View notes
?
Create notes
?
Edit notes
?
Work offline yes
Support imagery offset DB
?
Upload to OSM
?
Rendering
?
Accessibility
?

The GOL Tool is a command-line utility for building, managing, and querying Geo-Object Libraries (GOLs) and Geo-Object Bundles. It is part of the GeoDesk toolkit.

The GOL Tool converts OSM-PBF data into GOL files, downloads tilesets from remote repositories, runs queries with output in various formats, and performs maintenance tasks such as integrity checks. It is required as a companion tool for the Python, Java, and C++ SDKs, which use GOL files as their data source.

System Requirements

  • 64-bit system running Windows, macOS or Linux
  • For building GOLs from planet-size data, a minimum of 32 GB RAM is recommended; an SSD is highly recommended in any case

Installation

Download the GOL Tool from the GeoDesk download page and uncompress the ZIP file into a folder of your choice.

Alternatively, build the latest version from source at the GitHub repository.

Usage

Most commands follow this general form: 

gol <command> <gol-file> [<arguments>] [<options>]

Commands

Command Description
build Create a Geo-Object Library from OSM-PBF data
check Verify a Library's integrity
help Display documentation
info Provide basic file statistics
load Import tiles from a Geo-Object Bundle into a Library
map Display features on a Leaflet-based map
query Retrieve features and output them in various formats
save Write tiles from a Library to a Bundle

Building a GOL

The build command converts an OSM-PBF file into a GOL: 

gol build germany germany-latest.osm.pbf

This creates germany.gol. On a reasonably modern machine, country-size datasets take a few minutes; the full planet file takes about 20 minutes on a workstation with 8 cores and 32 GB RAM.

The resulting GOL is only 30% to 50% larger than the source PBF file. However, the build process requires temporary disk space equal to about 3 times the size of the PBF (up to 10 times for country-level extracts).

Sources of OSM-PBF data include the OSM planet file, GeoFabrik regional extracts, and BBBike extracts.

The build command supports a number of advanced options to control tiling structure, R-tree index branching, string table sizes, and area detection rules. See the full documentation for details.

Downloading Tilesets

The load command imports tiles from a Geo-Object Bundle into a GOL. The source can be a local file or a URL: 

gol load planet https://download.openplanetdata.com/osm/planet/gob/v1/planet-latest.osm.gob

To download only a specific region, use the --area (-a) option: 

gol load bodensee https://download.openplanetdata.com/osm/planet/gob/v1/planet-latest.osm.gob \
    -a 9.55,47.4,8.78,47.66,9.01,47.88,9.85,47.58,9.82,47.46

If the GOL does not yet exist, it is created automatically. Open Planet Data publishes a worldwide Geo-Object Bundle (updated daily).

Running Queries

The query command retrieves features matching a GOQL query and outputs them in various formats: 

gol query germany na[man_made=lighthouse] -f geojsonl

This retrieves all lighthouses (mapped as nodes or areas) and outputs line-separated GeoJSON. 

gol query germany w[highway=residential][oneway] -b 13.29,52.46,13.47,52.56 -f count

This counts all one-way residential streets within a bounding box covering central Berlin.

Output Formats

Format Description
brief Per-feature overview (default)
count Number of matching features only
csv Comma-separated values
geojson / geojsonl GeoJSON (traditional / one feature per line)
list Simple list of IDs
table Text-based table
wkt Well-Known Text (geometries only)
xml OSM XML

Additional options allow filtering by bounding box (-b) or polygon area (-a), selecting specific tag keys for output (-k), and controlling coordinate precision (-p).

Interactive Mode

When gol query is invoked without a query string, it enters an interactive Python-based session (requires GeoDesk for Python to be installed). This enables more sophisticated queries, including spatial joins, aggregation, and map visualization: 

gol query france

>>> paris = france("a[boundary=administrative][admin_level=6][name=Paris]").one
>>> paris.population
2165423
>>> streets = france("w[highway=primary][name]")(paris)
>>> streets.count
27525
>>> streets.map.show()

Displaying Features on a Map

The map command generates a Leaflet-based HTML map displaying query results: 

gol query germany na[amenity=pub] -a bavaria.poly -f map -t lon,lat,name > pubs.html

Other Commands

  • check — verifies the structural integrity of a GOL file, useful for troubleshooting or after an abnormal process termination
  • info — displays basic statistics about a GOL, such as feature counts and indexed keys
  • save — exports tiles from a Library into a Geo-Object Bundle for distribution
  • help — displays built-in documentation

Common Options

The following options are available across most commands:

Option Description
-a, --area Restrict the command to a polygon area (supports GeoJSON, WKT, or raw coordinates)
-b, --bbox Restrict the command to a bounding box (west,south,east,north)
-q, --quiet Minimal output
-s, --silent No output at all (check exit code for success/failure)
-v, --verbose Extra information

See Also

External Links

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=GOL_Tool&oldid=3005125"