# Working with Overture Maps Data

> How to download, organize, and use Overture Maps GeoParquet data with geolith.

## Downloading Overture Data

Overture Maps distributes data as GeoParquet files on Amazon S3. No AWS credentials are required.

### Full Planet Download

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

::warning
The full planet dataset is approximately 290 GB. Ensure you have sufficient disk space before downloading.
::

### Download Specific Themes

To save bandwidth, download only the themes you need:

```bash
# Buildings only (~80 GB)
aws s3 sync --no-sign-request \
  s3://overturemaps-us-west-2/release/2025.01.0/theme=buildings/ \
  ./data/overture/theme=buildings/

# Places only (~5 GB)
aws s3 sync --no-sign-request \
  s3://overturemaps-us-west-2/release/2025.01.0/theme=places/ \
  ./data/overture/theme=places/

# Divisions only (~2 GB)
aws s3 sync --no-sign-request \
  s3://overturemaps-us-west-2/release/2025.01.0/theme=divisions/ \
  ./data/overture/theme=divisions/
```

## Directory Structure

geolith expects the standard Overture Maps directory layout:

```
data/overture/
├── theme=base/
│   ├── type=land/
│   │   ├── part-00000.parquet
│   │   ├── part-00001.parquet
│   │   └── ...
│   ├── type=land_cover/
│   ├── type=land_use/
│   ├── type=water/
│   └── type=infrastructure/
├── theme=buildings/
│   └── type=building/
│       ├── part-00000.parquet
│       └── ...
├── theme=divisions/
│   ├── type=division/
│   ├── type=division_area/
│   └── type=division_boundary/
├── theme=places/
│   └── type=place/
├── theme=transportation/
│   ├── type=connector/
│   └── type=segment/
└── theme=addresses/
    └── type=address/
```

The `theme=X/type=Y/` structure is how Overture partitions its data. geolith scans this tree and maps each theme/type combination to the appropriate layer.

## Supported Themes and Types

| Theme | Types | geolith Layers |
| --- | --- | --- |
| `base` | `land`, `land_cover`, `land_use`, `water`, `bathymetry` | earth, water, landuse, landcover, bathymetry |
| `buildings` | `building` | buildings |
| `divisions` | `division`, `division_area`, `division_boundary` | boundaries, places |
| `places` | `place` | places, pois |
| `transportation` | `connector`, `segment` | roads, transit |

::note
Not all Overture types are used. geolith selectively reads the columns it needs from each type via column projection, skipping irrelevant data entirely.
::

## GERS Bridge Files

The [Overture Global Entity Reference System (GERS)](https://docs.overturemaps.org/gers/) provides bridge files that map OSM element IDs to Overture GERS UUIDs. geolith uses these to automatically deduplicate features that appear in both data sources.

### Downloading Bridge Files

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

This downloads approximately 32 GB of Parquet files covering three themes:

| Theme | Size | Files |
| --- | --- | --- |
| `buildings/` | ~21 GB | 480 files |
| `transportation/` | ~11 GB | 480 files |
| `divisions/` | ~255 MB | 4 files |

### Directory Layout

```
data/gers-bridge/
├── buildings/
│   ├── part-00000.zstd.parquet
│   ├── part-00001.zstd.parquet
│   └── ...
├── transportation/
│   ├── part-00000.zstd.parquet
│   └── ...
└── divisions/
    ├── part-00000.zstd.parquet
    └── ...
```

### Auto-Discovery

Place the `gers-bridge/` directory as a sibling of your `--data` directory:

```
data/
├── overture/          ← --data points here
│   ├── theme=buildings/
│   └── ...
└── gers-bridge/       ← auto-discovered
    ├── buildings/
    ├── transportation/
    └── divisions/
```

geolith automatically discovers bridge files when they exist at this location. No extra flags needed.

To override the location, use `--bridge-dir`:

```bash
geolith --data ./data/overture --bridge-dir /mnt/ssd/gers-bridge ...
```

To disable conflation entirely, use `--no-conflate`:

```bash
geolith --data ./data/overture --no-conflate ...
```

See the [GERS Conflation](/builder/guides/gers-conflation) guide for a detailed walkthrough.

## Data Freshness

Overture Maps publishes new releases roughly quarterly. Check the [Overture Maps releases page](https://docs.overturemaps.org/release/) for the latest version and update the S3 path accordingly.

When upgrading releases, download to a new directory to avoid mixing data from different versions:

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

Bridge files are also versioned — download the matching bridge file release for best deduplication results.