Friendly CLI to get Overture Maps data.

Overview

Overturist downloads and filters Overture Maps data for a specific place, a bounding box, or the whole world. It supports both guided interactive use and fully scripted runs; common selection and clipping strategies, and a local cache to speed up results.

Features

• Modes : run interactively or fully scripted with .env config and --arguments.
• Target : places, bounding boxes or the whole world.
• Flexible Lookups : find places by their name, GERS Id, or OSM relation Id.
• Disambiguation : search results are presented within the context of their hierarchy
• Themes : download all or a targeted subset by theme (e.g. transportation, places) or type (e.g. building, division)
• Selection : Filter results by intersection or containment of a division boundary or an exact bbox
• Clipping : Rewrite the geometry output to preserve geometry, clip selectively or clip all.
• Cache : release metadata, division lookups, and search history for faster results.
• I18n : results are presented and stored in your language.

Gallery

Installation

Requires Bun >=1.3.0, and currently only targets Linux because it depends on @duckdb/node-bindings-linux-x64.

Run Without Installing

bunx @saanseoi/overturist

Install Globally

bun install -g @saanseoi/overturist
overturist

Basic Usage

Start the interactive CLI:

bun overturist.ts

Download data non-interactively:

bun overturist.ts get --division <gersId>

Useful examples:

# Download one theme for a division
bun overturist.ts get --division <id> --theme buildings

# Resolve a division from an OSM relation id
bun overturist.ts info --osmId 913110

# Filter by bbox and keep only features fully within it
bun overturist.ts get --bbox 113.81724,22.13672,114.50249,22.56833 --frame bbox --predicate within

Use bun overturist.ts --help or bun overturist.ts --examples for the full CLI reference.

Advanced Topics

• Command reference and examples
• Configuration and environment variables
• Spatial filtering and geometry modes
• Output layout and cache behavior
• Release process
• Development notes

Limitations

The Overture Maps Foundation has a monthly release cadence and keeps 60 days of releases available in S3. So usually only the latest 2 releases are available for download.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Made with <3 in