Overview

When building tiles from both OpenStreetMap and Overture Maps, many features exist in both datasets — the same building, road, or administrative boundary appears twice. geolith uses the Overture Global Entity Reference System (GERS) to identify and eliminate these duplicates automatically.

Key concept: Overture publishes "bridge files" — Parquet files that map OSM element IDs to GERS UUIDs. When geolith finds a match, the OSM feature is skipped and the Overture version is kept.

How It Works

1. Bridge File Loading

At pipeline start, geolith loads all bridge Parquet files into a BridgeIndex — a hash map from OSM element IDs (e.g., w1182486582@1) to GERS UUIDs. This index is thread-safe and shared across all reader threads.

2. OSM Deduplication

During OSM PBF reading, each feature's element ID is checked against the BridgeIndex. If a match is found, the OSM feature is dropped — Overture's version (already loaded in the Overture reading phase) takes precedence.

3. Spatial Fallback

For themes without GERS bridge files (places, POIs, landcover, water), geolith falls back to R-tree/H3 spatial deduplication. Features from OSM and Overture that overlap within a configurable distance threshold are deduplicated based on attribute similarity.

Setup

Download Bridge Files

aws s3 sync --no-sign-request \
  s3://overturemaps-us-west-2/bridgefiles/2026-02-18.0/dataset=OpenStreetMap/ \
  ./data/gers-bridge/

This produces approximately 32 GB across three themes:

• buildings/ — 480 Parquet files (~21 GB)
• transportation/ — 480 Parquet files (~11 GB)
• divisions/ — 4 Parquet files (~255 MB)

Directory Layout

Place bridge files as a sibling of your Overture data directory:

data/
├── overture/          ← --data
├── gers-bridge/       ← auto-discovered
│   ├── buildings/
│   │   ├── part-00000.zstd.parquet
│   │   └── ...
│   ├── transportation/
│   │   ├── part-00000.zstd.parquet
│   │   └── ...
│   └── divisions/
│       ├── part-00000.zstd.parquet
│       └── ...
├── planet-latest.osm.pbf
└── natural_earth.sqlite

Configuration

Auto-Discovery (Default)

No flags needed. geolith checks for gers-bridge/ next to --data automatically:

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles

If bridge files are found, the log shows:

INFO geolith::pipeline: Loaded 1099 GERS bridge files (buildings: 480, transportation: 480, divisions: 4)

Explicit Bridge Directory

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --bridge-dir /mnt/ssd/gers-bridge

Individual Bridge Files

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --bridge-files ./bridges/buildings.parquet \
  --bridge-files ./bridges/transportation.parquet

Disable Conflation

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons \
  --water-polygons ./data/water-polygons \
  --output ./data/planet-vector.pmtiles \
  --no-conflate

Discovery Priority

geolith checks for bridge files in this order:

1. --bridge-dir <path> — explicit directory flag
2. --bridge-files <path> — individual file flags (additive with --bridge-dir)
3. gers-bridge/ sibling — auto-discovered next to --data

If none are found, conflation is silently disabled and both OSM + Overture features are included as-is.

Covered Themes

Impact

With GERS conflation enabled on a planet build:

• Buildings — eliminates millions of duplicate building footprints
• Roads — removes duplicate road segments (OSM highways ↔ Overture transportation)
• Divisions — deduplicates administrative boundaries
• Output size — typically 15–30% smaller than without conflation
• Visual quality — no overlapping/doubled geometry artifacts

Troubleshooting

"No bridge files found" — check that gers-bridge/ is a sibling of your --data directory, or use --bridge-dir explicitly.

"Loaded 0 bridge files" — the directory exists but contains no .parquet files. Verify the download completed.

Large output with conflation — some features may not have GERS matches (new OSM edits, Overture coverage gaps). This is expected. Spatial fallback handles remaining themes.