Skip to main content Link Search Menu Expand Document (external link)

Five-Minute Tutorial

This tutorial assumes that you are already familiar with OpenStreetMap and its data model. If not, read our Introduction to OSM or visit the official OSM website.

Create a Feature Library

  • Download and install the GOL command-line utility

  • Download some OSM data (in PBF format). We suggest starting with a subset for a single country (or smaller part). For example, Germany (file size: 3.5 GB) can be downloaded from GeoFabrik or BBBike.

  • Turn the PBF file into a Geographic Object Library:

    gol build germany germany-latest.osm.pbf

    On a multi-core workstation with at least 24 GB of RAM, this should take a few minutes; on an 8-GB dual-core laptop, expect 20 minutes or more. The output will look like this:

    Building germany.gol from germany-latest.osm.pbf using default settings...
    Analyzed germany-latest.osm.pbf in 20s 
    Sorted 86,432,126 features in 1m 13s
    Validated 1023 tiles in 36s
    Compiled 1023 tiles in 1m 24s
    Linked 1023 tiles in 8s
    Build completed in 3m 43s  

Use Feature Libraries in Java

Add this Maven dependency to your project:


Import the GeoDesk packages:

import com.geodesk.core.*;
import com.geodesk.feature.*;

Open the library:

FeatureLibrary library = new FeatureLibrary("germany.gol");   

Create a query:

var lighthouses ="na[man_made=lighthouse][name][height]");   

This returns a collection of Feature objects representing lighthouses that have names and whose height has been recorded (na indicates that we want features that are mapped as nodes or areas — see Geo-Object Query Language).

Iterate through the features:

for(Feature f: lighthouses)
    System.out.format("%s is %f meters tall.\n", 
        f.stringValue("name"), f.doubleValue("height"));      

Typically we want only a specific subset of the collection. The most common case is a bounding-box query:

Box bbox = Box.ofWSEN(8.42, 53.75, 9.07, 53.98);
    // longitude/latitude West, South, East, North
for(Feature f: ...

Other filters include:

  • Filter by type: .nodes(), .ways(), .relations()

  • Spatial predicates: .select(...): intersects(...), contains(...), overlaps(...)

Filters can be combined:


Work with individual features

Retrieve a feature’s tags:

Tags tags = feature.tags();
Map<String,Object> tagMap = feature.tags().toMap();

Get a specific tag value by key:

feature.stringValue("opening_hours") // returns empty string if tag not present
feature.intValue("maxspeed")         // 0 if tag not present or non-numeric

Get its type and ID:

FeatureType type = feature.type();   // NODE, WAY or RELATION
long osmId =;     

Its location:

feature.lon()  // degrees longitude  // degrees latitude
feature.x()    // Mercator-projected X-coordinate
feature.y()    // Mercator-projected Y-coordinate

Its length (meters) or area (square meters):

feature.length()  // 0 if not linear
feature.area()    // 0 if not an area

Its JTS geometry:

feature.toGeometry()  // Point for a Node
                      // LineString or LinearRing for a non-area Way
                      // Polygon for a Way that represents an area
                      // Polygon or MultiPolygon for an area Relation
                      // GeometryCollection for all other Relations


Way is a subtype of Feature.

for(Way way: library.ways("[highway=residential]")) ...

Retrieve the nodes that make up a way:


Get a collection of specific kinds of nodes:

way.nodes("[traffic_calming]")  // speed bumps etc.

Or simply iterate the way:

for(Node node: way) 

(Iteration only retrieves nodes that have tags or are part of a relation; nodes() returns all nodes).


Get the relations to which a feature belongs:

for(Relation rel: feature.parentRelations()) 

Retrieve a relation’s members:

for(Feature member: rel.members())

Discover a member’s role:

member.role()   // "stop", "main_stream", etc.

Find members with a specific role: 0.2

Node capital = rel.memberNodes("[role=admin_centre]").first();

Or simply iterate:

for(Feature member: rel)

Wrapping up

GeoDesk enables you to:

  • Create compact spatial databases (“Feature libraries”) based on OpenStreetMap data
  • Select features using a powerful query language and access their properties (“tags”) and geometries
  • Traverse the relationships between nodes, ways and relations
  • Leverage the Java Topology Suite for advanced geometric operations

Learn more