# Quick Start

> Generate your first PMTiles archive from 6 data sources in minutes.

## 1. Download Data

geolith reads from 6 data sources. Download each one:

### Overture Maps GeoParquet (~290 GB)

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

### OpenStreetMap PBF (~85 GB)

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

### Natural Earth SQLite (~1 GB)

```bash
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)

```bash
# 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)

```bash
# 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:

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

::tip
Place bridge files in a `gers-bridge/` directory next to your Overture data directory and conflation enables automatically. See the [GERS Conflation](/builder/guides/gers-conflation) guide for details.
::

## 2. Generate Tiles

Run geolith with all 6 sources:

```bash
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:

```bash
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:

- **[PMTiles Viewer](https://protomaps.github.io/PMTiles/)** — drag and drop your `.pmtiles` file
- **[MapLibre GL JS](https://maplibre.org/)** — load via the `pmtiles` protocol
- **[QGIS](https://qgis.org/)** — open as a vector tile source

```javascript
// 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, MLT columnar encoding (default) or MVT protobuf (`--tile-format mvt`)
6. **Write** — Hilbert curve ordering, content deduplication, two-level directory (PMTiles) or SQLite WAL (MBTiles)

See the [Pipeline Architecture](/builder/architecture/pipeline) page for a detailed breakdown.