aef-download

aef-download

aef-download is a Python package and CLI for downloading yearly AlphaEarth Foundations embeddings for arbitrary regions from the public AlphaEarth mosaic hosted on Source Cooperative.

It is designed for workflows where you want to:

• download one or more years for a custom region
• use a boundary file or a direct bbox
• write local yearly Zarr stores
• optionally mask pixels outside the requested polygon
• resume interrupted downloads safely

Features

• boundary files readable by geopandas (GeoJSON, GPKG, SHP, and more)
• direct bbox input in EPSG:4326
• yearly downloads for 2017-2025
• local yearly Zarr outputs
• optional boundary mask
• optional dequantized float32 output
• resumable downloads via .progress.json
• both CLI and Python API

Install

From PyPI

Once published:

pip install aef-download

From GitHub

pip install git+https://github.com/Caojun-whu/aef-download.git

From a local clone

pip install -e .

Data source

The package reads from the public AlphaEarth mosaic:

• https://source.coop/tge-labs/aef-mosaic

This package downloads regional subsets from that public mosaic. It does not download the full global dataset.

By default, downloaded embeddings are stored as quantized int8. Use dequantize=True or --dequantize if you want float32 outputs instead.

CLI quickstart

Download one year using a boundary file:

aef-download download-year \
  --boundary region.geojson \
  --year 2022 \
  --output-dir ./out \
  --mask-boundary

Download multiple years:

aef-download download-years \
  --boundary region.geojson \
  --year-start 2017 \
  --year-end 2025 \
  --output-dir ./out \
  --mask-boundary

Download using a bbox:

aef-download download-year \
  --bbox 112.95 22.56 114.05 23.93 \
  --year 2022 \
  --output-dir ./out

Estimate storage without downloading:

aef-download estimate-years \
  --boundary region.geojson \
  --year-start 2017 \
  --year-end 2025

Python API quickstart

from aef_download import download_year, estimate_year

estimate = estimate_year(
    boundary_path="region.geojson",
    year=2022,
)
print(estimate["estimated_storage"])

output = download_year(
    boundary_path="region.geojson",
    year=2022,
    output_dir="./out",
    mask_boundary=True,
)
print(output)

Using a bbox:

from aef_download import download_year

output = download_year(
    bbox=(112.95, 22.56, 114.05, 23.93),
    year=2022,
    output_dir="./out",
)
print(output)

Output format

Each year is written as:

• {prefix}_{year}.zarr
• {prefix}_{year}.zarr.progress.json

The Zarr store contains:

• embeddings
• x
• y
• mask when mask_boundary=True

Typical Zarr attributes include:

• year
• bbox
• boundary_source
• mask_boundary
• dequantized
• source mosaic settings

Resume behavior

Downloads are written chunk by chunk. If interrupted, rerun the same command without --overwrite; completed chunks will be skipped and the download will resume from the progress file.

Notes

• Supported years are 2017-2025.
• Bboxes are interpreted as (xmin, ymin, xmax, ymax) in EPSG:4326.
• Boundary files are normalized to EPSG:4326 before slicing the AlphaEarth mosaic.

Development

Run tests:

python -m pytest tests -q

Check the CLI:

aef-download --help

Build a release:

python -m build
python -m twine check dist/*