Documentation

1. Download Data

geolith reads from 6 data sources. Download each one:

Overture Maps GeoParquet (~290 GB)

aws s3 sync --no-sign-request \
  s3://overturemaps-us-west-2/release/2025.01.0/ \
  ./data/overture/

OpenStreetMap PBF (~85 GB)

download-osm planet -- -d ./data/
# or download from https://planet.openstreetmap.org/

Natural Earth SQLite (~1 GB)

wget -O ./data/natural_earth.sqlite \
  https://naciscdn.org/naturalearth/packages/natural_earth_vector.sqlite.zip
unzip natural_earth_vector.sqlite.zip -d ./data/

Land & Water Polygons (~2.4 GB combined)

# Land polygons (EPSG:3857)
wget https://osmdata.openstreetmap.de/download/land-polygons-split-3857.zip
unzip land-polygons-split-3857.zip -d ./data/

# Water polygons (EPSG:3857)
wget https://osmdata.openstreetmap.de/download/water-polygons-split-3857.zip
unzip water-polygons-split-3857.zip -d ./data/

India Boundary GeoJSON (optional, ~10 MB)

# Required for correct India border rendering
wget -O ./data/india-boundary.geojson \
  https://raw.githubusercontent.com/datameet/maps/b3fbbde595310b397a55d718e0958ce249a4fa1f/Country/india-composite.geojson

GERS Bridge Files (optional, ~32 GB)

For automatic OSM ↔ Overture deduplication:

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

Place bridge files in a gers-bridge/ directory next to your Overture data directory and conflation enables automatically. See the GERS Conflation guide for details.

2. Generate Tiles

Run geolith with all 6 sources:

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons-split-3857 \
  --water-polygons ./data/water-polygons-split-3857 \
  --india-boundary ./data/india-boundary.geojson \
  --output ./data/planet-vector.pmtiles \
  --max-zoom 15 \
  --threads 10 \
  --tmpdir ./data/tmp \
  --node-store ./data/node.store

For a quick regional test, add --bbox to limit the area:

geolith \
  --data ./data/overture \
  --osm-pbf ./data/planet-latest.osm.pbf \
  --natural-earth ./data/natural_earth.sqlite \
  --land-polygons ./data/land-polygons-split-3857 \
  --water-polygons ./data/water-polygons-split-3857 \
  --output ./data/india.pmtiles \
  --bbox 68.0,6.5,97.5,37.2 \
  --max-zoom 15

3. View the Output

Open your PMTiles file with any compatible viewer:

// MapLibre GL JS with pmtiles protocol
import { Protocol } from 'pmtiles';
import maplibregl from 'maplibre-gl';

const protocol = new Protocol();
maplibregl.addProtocol('pmtiles', protocol.tile);

const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    sources: {
      openmaptiles: {
        type: 'vector',
        url: 'pmtiles://./planet-vector.pmtiles',
      },
    },
    layers: [],
  },
});

What Happens Under the Hood

  1. Read — 6 data sources are read in parallel: Overture GeoParquet (column projection + bbox pushdown), OSM PBF (2-pass: node cache + feature extraction), Natural Earth SQLite, land/water shapefiles (EPSG:3857→WGS84), India boundary GeoJSON
  2. Conflate — GERS bridge files deduplicate features that exist in both OSM and Overture (buildings, roads, divisions)
  3. Process — Features are projected to Web Mercator, assigned to tiles, clipped, and simplified per zoom level
  4. Sort — Tile entries are externally sorted by (tile_id, layer, sort_key) using LZ4-compressed chunks
  5. Encode — Per-tile polygon merge, deduplication, MVT protobuf encoding, gzip compression
  6. Write — Hilbert curve ordering, content deduplication, two-level directory (PMTiles) or SQLite WAL (MBTiles)

See the Pipeline Architecture page for a detailed breakdown.