DOCSEARCHbyAlgolia
Submit Docs

Overture Maps Python Tools

repository·main·Indexed 42 days ago

https://github.com/overturemaps/overturemaps-py

Official Python tools and CLI for interacting with Overture Maps data. Features include downloading normalized geospatial map data in GeoJSON, GeoJSONSeq, and GeoParquet formats, loading data into GeoPandas GeoDataFrames, and querying the GERS Registry and changelogs. Version 1.0.2 provides utilities for spatial filtering via bounding boxes and STAC catalog acceleration.

Tokens
11.4K
Snippets
46
Records
60
Agent score
51%

What's inside Overture Maps

  1. Performance and Reliability Characteristics

    main

    overturemaps is designed for high-performance geospatial data streaming with the following characteristics:

    • Streaming Architecture: All data flows as RecordBatch streams to avoid loading full datasets into memory.
    • Efficient Data Access: Uses STAC indexing to skip non-intersecting Parquet shards and PyArrow predicate pushdown for row-group level filtering.
    • Anonymous S3 Access: All S3 I/O is performed anonymously; no credentials are required or stored.
    • Silent Fallbacks: If a STAC index lookup fails, the library silently attempts a direct S3 scan to ensure reliability.
    • Validation: Input such as BBox bounds and GERS UUIDs are strictly validated before being used in network requests or filter expressions to prevent injection or errors.

  2. Understand state management and sidecar files

    main

    The library uses a sidecar convention to manage state for downloads and operations.

    • Sidecar File Naming: A state file is created with the suffix .state appended to the output path. For example, if your output is boston.geojson, the state file will be boston.geojson.state.
    • save_state: This function creates any missing parent directories and writes the state as a JSON file with indent=2. The output field in the JSON stores the absolute, resolved path.
    • load_state: This function is designed to be non-failing. It returns None if the file is missing, if there is a FileNotFoundError, a JSONDecodeError, or a KeyError. Callers should always check for None before proceeding.

  3. Overture Feature Themes and Types

    main

    Overture data is organized into 5 themes containing 15 specific feature types. You must specify one of these types when querying or downloading.

    ThemeTypes
    addressesaddress
    basebathymetry, infrastructure, land, land_cover, land_use, water
    buildingsbuilding, building_part
    divisionsdivision, division_area, division_boundary
    placesplace
    transportationconnector, `segment

  4. Download Overture data with the `download` command

    main

    The download command streams Overture data from S3 in a specified format. You can download the entire dataset for a specific type or clip the download to a bounding box using --bbox to minimize data transfer.

    To find coordinates for the --bbox flag, you can use tools like boundingbox.klokantech.com which exports coordinates in the required west,south,east,north format.

    overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson

  5. Query feature changes with the `changelog` command

    main

    The changelog command queries GERS feature changes across different releases. You can use summary to see high-level changes for a theme or query to find specific changes within a bounding box.

    overturemaps changelog summary --theme=buildings
overturemaps changelog query --theme=places --bbox=-71.068,42.353,-71.058,42.363

  6. Best Practices: CLI Output and Observability

    main

    When using the overturemaps CLI or building tools around it, follow these output discipline rules:

    • Data to stdout: GeoJSON, GeoJSONSeq, and GeoParquet content is sent to stdout when no output file (-o) is specified. Never print diagnostic information to stdout.
    • User Info to stderr: All warnings, progress bars (tqdm), GERS information, and error messages are sent to stderr.
    • Exit Codes:
      • 0: Success, true, or data is up-to-date.
      • 1: Failure, false, or data is stale.

  7. Look up a feature by GERS ID with the `gers` command

    main

    The gers command looks up a specific feature in the GERS Registry. If the feature is present in the latest release, it is written to the requested format.

    overturemaps gers 08f28d1c-bf17-4c5c-bc1b-0f1f7b0d4abc -f geojsonseq

  8. Run performance benchmarks locally

    main

    To run the project's performance benchmarks on your local machine, use uv to synchronize the development environment and then execute pytest against the benchmarks directory. Note that the reported benchmarks in the documentation were performed using synthetic data on Apple M-series hardware.

    uv sync --group dev
pytest benchmarks/ -v

  10. Download Overture data with the CLI

    main

    Use the download command to retrieve Overture geospatial data. You can specify a bounding box (--bbox), the output file format (-f), the data type (--type), and the output filename (-o).

    overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet

  11. Inspect Overture releases with the `releases` command

    main

    The releases command allows you to inspect published Overture releases. Use subcommands like list, latest, or exists to check availability.

    overturemaps releases list
overturemaps releases latest
overturemaps releases exists 2025-09-24.0

  12. Install overturemaps-py

    main

    You can install the overturemaps package using pip, Homebrew, or conda-forge. For a quick, one-off execution without permanent installation, you can use uvx.

    # Using pip
pip install overturemaps

# Using Homebrew
brew install overturemaps

# Using conda-forge
conda install -c conda-forge overturemaps

# Using uvx (one-off execution)
uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet