Fast, single-file OpenStreetMap queries in Rust

regol is an independent, pure-Rust GeoDesk GOL 2.0 reader, spatial query engine, and OSM PBF compiler—built for country- and continent-scale lookups with no C, SQLite, or native GeoDesk dependencies.

Apache-2.0 · Rust 1.85+ · #![forbid(unsafe_code)] without mmap

# Build a GOL 2.0 file from OpenStreetMap PBF
$ regol build region.osm.pbf region.gol

# Query cafés in a GeoJSON polygon as GeoJSONL
$ regol query region.gol 'na[amenity=cafe]' \
    --area district.geojson \
    -f geojsonl > cafes.geojsonl

# Export roads in a bounding box to CSV
$ regol query region.gol 'w[highway]' \
    --bbox=-0.14,51.49,-0.10,51.52 \
    -f csv --keys id,name,highway

Single-file GOL 2.0

Reorganizes .osm.pbf snapshots into zoom-pyramid tiles, tag categories, and Hilbert-ordered R-trees so queries read only overlapping branches.

100% pure Rust

Zero C toolchains, SQLite staging databases, or external GeoDesk runtimes. Enforces #![forbid(unsafe_code)] when mmap is not enabled.

CLI & embeddable crate

Embed regol inside Rust applications or use regol-cli to build, inspect, verify CRC32C checksums, query, and export GIS and OSM formats.

Disk, RAM, or S3

Generic over positioned byte reads (Source): run on local disks, bounded caches, immutable memory maps, or custom HTTP/object-storage backends.

Pure-Rust PBF compiler

regol build compiles raw or zlib-compressed .osm.pbf snapshots in parallel in memory and atomically publishes the finished .gol file—ready for local queries or remote range-read serving.

  • Presets for real workloads: --preset vector-tiles for S3 range reads and --preset compact for smaller metadata headers.
  • Layout tuning: control tile size (--target-tile-kib), even zoom steps (--even-zooms), border duplication, and per-tile R-tree fanout.
  • Embeddable: enable the optional build Cargo feature to compile GOLs straight from Rust via regol::build.
Pipeline from OSM PBF through parallel Rust builder to single-file GOL 2.0 layout INPUT .osm.pbf Nodes · Ways Relations · Tags Raw / zlib regol build Parallel in-memory String dict Tile pyramid Hilbert R-tree 100% safe Rust region.gol (GOL 2.0) Header + CRC32C Global Dictionary Tile Index Indexed Tiles z6 z8 z10

GOQL & spatial engine

Prepare a GeoDesk Query Language (GOQL) selector once to resolve tag dictionary codes and category bitmasks, then reuse it across bounding boxes, spatial filters, parallel counts, and zero-allocation streaming scans.

  • Exact spatial predicates: Intersects, Within, Contains, CoveredBy, Touches, Overlaps, Crosses, Disjoint, and WithinDistance.
  • Full OSM relationships: combine FeatureSets with and, or, without, and traverse member_set, parent_set, and connected_to.
  • Typed spherical measurements: lengths, perimeters, distances, and areas returned as type-safe uom SI quantities.
Four-stage GOL query execution pipeline from GOQL preparation to exact geometry matches 1 Prepare GOQL selector Resolve tag codes & category mask once na[amenity=cafe] 2 Tile index pruning Read only tiles overlapping query bounds bbox → tiles 3 Per-tile R-tree & tag scan Skip non-matching categories & branches category + bbox 4 Exact predicate & results Exact geometry, relations, or SI units Feature / count

Command-line tool

regol-cli bundles build, info, check, and query into one standalone binary. Queries memory-map immutable files, load the string dictionary on demand, and encode large exports in parallel while preserving query order.

Export matching features as count, ids, geojson, geojsonl, wkt, csv, xml, or pbf—with GeoJSON antimeridian splitting, polar cap closure, configurable coordinate precision, custom CSV columns, and --complete-relations for self-contained PBF extracts.

regol CLI workflow
# Inspect metadata, indexed keys, and tile counts
$ regol info region.gol

# Verify CRC32C checksums, R-tree bounds, and links
$ regol check region.gol

# Extract a PBF slice for a bounding box
$ regol query region.gol 'w[highway]' \
    --bbox=-0.14,51.49,-0.10,51.52 \
    -f pbf > roads.osm.pbf

# Export building areas inside a GeoJSON polygon
$ regol query region.gol 'a[building]' \
    --area boundary.geojson \
    -f geojson > buildings.geojson

Benchmarks

Cross-engine benchmarks comparing regol on regional OpenStreetMap extracts are maintained in gol-bench. Placeholder figures below will be replaced with reproducible runs before release.

Workload regol Reference Notes
PBF → GOL build TBD TBD Great Britain .osm.pbf, multi-threaded build
GOL file size TBD TBD Default layout (16 MiB target tiles)
Full-region tag count TBD TBD na[amenity=cafe], warm mmap, parallel count
Bbox query & GeoJSON export TBD TBD w[highway], parallel ordered encoding
Polygon spatial filter TBD TBD a[building] with --area GeoJSON boundary

Placeholder table — hardware specs, dataset snapshot dates, exact CLI flags, and median timings across runs will be published alongside the benchmark scripts.

Quick start

Requires Rust 1.85 or later. Install the standalone command-line tool or add the regol library to your Cargo project.

Install the CLI

The regol-cli crate provides the regol binary with build, info, check, and query.

Shell
cargo install --locked regol-cli

regol build region.osm.pbf region.gol
regol query region.gol 'na[amenity=cafe]'

View regol-cli on crates.io →

Embed in Rust

Optional Cargo features: parallel (default), mmap, build, and way-checkpoints.

Cargo.toml
[dependencies]
regol = "0.2"

# Optional PBF builder & mmap features:
# regol = { version = "0.2",
#   features = ["mmap", "build"] }

Read library documentation on docs.rs →

Free and open-source software

regol is licensed under the Apache License, Version 2.0. Explore the full API documentation, cargo feature matrix, and GOL 2.0 format compatibility notes.