The `gs://alphaearth_foundations_custom` GCS bucket contains sample datasets of
Custom Satellite Embeddings made up of COG (Cloud Optimized GeoTIFF) files
generated by AlphaEarth Foundations.

## License

This collection of datasets is licensed under
[CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) and requires the
following attribution text: "Custom Satellite Embeddings from AlphaEarth
Foundations are produced by Google and Google DeepMind." Use of these public
datasets is subject to the
[Google Cloud Acceptable Use Policy](https://cloud.google.com/terms/aup).

## Available datasets

The following is a list of datasets in this bucket. It contains a dataset's
name, description, and general area encompassed by the dataset. Note that time
intervals here use an inclusive start time and an exclusive end time.

- **name** : corcoran_city_2026_agricultural_change   

  **area** : Corcoran and surrounding agricultural region, California, USA   

  **description**: Winter bare soil (Dec 15, 2025 - Feb 15, 2026) and spring
  peak greenness (Mar 15 - May 15, 2026) embeddings capturing agricultural
  crop dynamics over two seasonal windows.

- **name** : futaleufu_argentina_2026_fire_scar   

  **area** : Los Alerces National Park and surrounding region, Futaleufú
  Department, Chubut Province, Argentina   

  **description**: Pre-fire (Dec 1-31, 2025) and post-fire (Mar 1-31, 2026)
  embeddings capturing wildfire burn scar extent and forest canopy disturbance
  from the 2026 Los Alerces Wildfire.

- **name** : king_county_2025_monthly   

  **area** : King County, Washington, USA   

  **description**: Calendar-month embeddings for the King County
  administrative area for the first six months of 2025, covering diverse urban
  city infrastructure and forested land.

- **name** : meloland_california_2026_crop_cycles   

  **area** : Meloland and surrounding agricultural fields, Imperial Valley,
  California, USA   

  **description**: Six sequential monthly (15th to 15th) embedding time steps
  (mid-November 2025 through mid-May 2026) tracking multi-crop rotation
  cycles.

- **name** : pacific_palisades_2025_fire   

  **area** : Pacific Palisades and surrounding coastal hills, Los Angeles,
  California, USA   

  **description**: Pre-fire (Dec 7, 2024 - Jan 7, 2025) and post-fire (Jan 7 -
  Feb 7, 2025) 31-day embeddings capturing Palisades Fire wildfire impact and
  land cover change.

- **name** : theewaterskloof_dam_2026_water_change   

  **area** : Theewaterskloof Dam, Theewaterskloof Local Municipality, South
  Africa   

  **description**: Dry-season (Jan 1-31, 2026) and wet-season recharge (Apr
  15 - May 15, 2026) embeddings capturing reservoir water surface area
  changes.

## Directory structure

All sample datasets are organized under the
`gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/` prefix:

```text
gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/
└── {dataset_name}/
    ├── aef_index.parquet
    ├── manifest.txt
    └── {start_date}_{end_date}/
        └── {image_id}/
            ├── data.tiff
            └── image_manifest.json
```

Each dataset has its own directory containing a dataset-level
`aef_index.parquet` GeoParquet index file, a dataset-level `manifest.txt` file,
and one or more time interval subdirectories.

These time interval subdirectories are named using the pattern
`{start_date}_{end_date}`, where the start date is inclusive and the end date is
exclusive. Both dates are formatted as `yyyyMMdd` and are in the UTC timezone.
For example, a subdirectory for the month of June 2025 would be named
`20250601_20250701`, which corresponds to a time interval from
`2025-06-01T00:00:00Z` (inclusive) to `2025-07-01T00:00:00Z` (exclusive).

Each time interval directory contains a subdirectory for each image embedding
within that time interval, named with an image identifier (`{image_id}`) that
uniquely identifies the image within the dataset. Each `{image_id}` subdirectory
contains a `data.tiff` COG file of the pixel data and a sidecar
`image_manifest.json` file that is used to register the data in Earth Engine.

## File structure

The internal structure of each COG file---including its 8192x8192 pixel
dimensions, 64 channels (`A00` through `A63`), normalized overview pyramids,
signed 8-bit integer quantization, and `-128` `NoData` mask value---is identical
to the annual Satellite Embedding COGs. Unlike the annual COGs, valid pixels in
each sample tile typically cover only a subset of the 8192x8192 grid
corresponding to the region of interest, with all remaining pixels masked as
`-128` (`NoData`). For complete details on the COG layout, see the
[File structure](https://developers.google.com/earth-engine/guides/aef_on_gcs_readme.md.txt#file-structure) section
of the AlphaEarth Foundations GCS data guide.

The path of each COG file also carries some information. For example, consider
the file at
`gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/pacific_palisades_2025_fire/20250107_20250207/x1evicvaet1mupt13-0000008192-0000000000/data.tiff`.
As evident in the path, this file is part of the embeddings for the 2025
Palisades Fire in Los Angeles County. This particular file contains embeddings
that summarize a time period from January 7th, 2025 (inclusive) to February 7th,
2025 (exclusive). The `x1evicvaet1mupt13-0000008192-0000000000` subdirectory
name uniquely identifies the `data.tiff` COG in the
`pacific_palisades_2025_fire` dataset. This identifier is an opaque UUID.

Alternatively, this file metadata and more can be extracted from the COG's
`image_manifest.json` file found at
`gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/pacific_palisades_2025_fire/20250107_20250207/x1evicvaet1mupt13-0000008192-0000000000/image_manifest.json`.
This file is a JSON representation of an Earth Engine Image Manifest. The JSON
structure of an Image Manifest is defined in the
[Image Manifest guide](https://developers.google.com/earth-engine/guides/image_manifest.md.txt). For a full
description of the contents in a given `image_manifest.json` file, see the
[Image manifest](https://developers.google.com/earth-engine/guides/custom_embedding_samples_on_gcs_readme.md.txt#image-manifest) section.

## De-quantization

Raw pixel values in each channel are signed 8-bit integers in the range \[-127,
127\] (with `-128` reserved as the "no data" value) and must be de-quantized to
produce analysis-ready floating-point values in the range \[-1, 1\]. For the
de-quantization mapping and instructions on creating downsampled pyramids, see
the [De-quantization](https://developers.google.com/earth-engine/guides/aef_on_gcs_readme.md.txt#de-quantization)
and
[Create downsampled pyramids](https://developers.google.com/earth-engine/guides/aef_on_gcs_readme.md.txt#create_downsampled_pyramids)
sections of the AlphaEarth Foundations GCS data guide.

## Manifests and indexes

To facilitate discovering, iterating over, and registering embedding tiles, each
dataset provides two types of manifests---a dataset-level list of COG files
(`manifest.txt`) and a per-image metadata manifest (`image_manifest.json`)---along
with a dataset-level GeoParquet spatial index (`aef_index.parquet`).

### Dataset manifest

Every dataset includes a `manifest.txt` file located at the root of its
directory:
`gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/{dataset_name}/manifest.txt`

This is a plain-text file containing the full Google Cloud Storage URI for each
`data.tiff` file in the dataset, separated by newlines.

### Image manifest

Alongside every `data.tiff` file is a sidecar `image_manifest.json` file:
`gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/{dataset_name}/{start_date}_{end_date}/{image_id}/image_manifest.json`

This JSON file follows the
[Earth Engine Image Manifest specification](https://developers.google.com/earth-engine/guides/image_manifest.md.txt)
and describes the tile's source files, band structure, temporal bounds, and
spatial coverage.

While standard manifest fields (such as `tilesets` and `bands`) follow standard
Earth Engine conventions, there are several key details to note:

- **`name`** : Left empty (`""`) in GCS. When using this manifest to register an image in an Earth Engine asset collection, the client must supply the target asset ID (e.g., `projects/{project}/assets/{collection}/{image_id}`). See [Load a dataset into Earth Engine](https://developers.google.com/earth-engine/guides/custom_embedding_samples_on_gcs_readme.md.txt#load_a_dataset_into_earth_engine) for details.
- **`start_time` \& `end_time`** : Specify the start (inclusive) and end (exclusive) timestamps for the composite time period in UTC formatted as ISO 8601 (e.g., `2026-03-15T00:00:00+00:00`).
- **`footprint`** : A closed polygon in pixel coordinates outlining a region containing valid pixels. Note that missing pixels can still exist within the polygon - such is the case for complex embedding geometries like that of `king_county_2025_monthly`.
- **`properties`** : Key-value metadata specific to the embedding, including:
  - `IMAGE_ID`: The unique identifier of the image within the dataset.
  - `DATASET`: The dataset name.
  - `DATASET_VERSION`: The dataset version.
  - `START_DATE` \& `END_DATE`: The start (inclusive) and end (exclusive) dates of the time interval covered by the image, formatted as `YYYY-MM-DD`.
  - `MODEL_VERSION`: The version string uniquely identifying the model version used to produce the image.
  - `PROCESSING_SOFTWARE_VERSION`: The version string uniquely identifying the model data processing software used to produce the image.
  - `UTM_ZONE`: The UTM zone of the coordinate reference system used to produce the image.

### GeoParquet index

Every dataset includes a GeoParquet spatial index file located at the root of
its directory:
`gs://alphaearth_foundations_custom/custom_satellite_embedding/v1/{dataset_name}/aef_index.parquet`

This index contains one entry for each `data.tiff` file in the dataset and
provides spatial and temporal metadata to help determine which files cover a
given area and time period:

- **`geometry`** : The geometry of the file as a WGS84 (`EPSG:4326`) polygon. For details on how this polygon is computed from the pixel array's UTM bounding box and clipped to UTM zone bounds, see the [Geometry processing](https://developers.google.com/earth-engine/guides/aef_on_gcs_readme.md.txt#geometry-processing) section of the AlphaEarth Foundations GCS data guide. Note that this polygon reflects the bounds of the full 8192x8192 pixel array and does not account for the validity of individual pixels.
- **`crs`** : The CRS of the UTM zone the image belongs to as an EPSG code, such as `EPSG:32610`.
- **`path`** : The Google Cloud Storage URI (`gs://...`) of the `data.tiff` COG file.
- **`dataset`**: The dataset name.
- **`start_date` \& `end_date`** : The start (inclusive) and end (exclusive) dates of the time interval covered by the image, formatted as `YYYY-MM-DD`.
- **`image_id`**: The unique identifier of the image within the dataset.
- **`utm_zone`** : The UTM zone of the image, such as `10N`.
- **`utm_west`, `utm_south`, `utm_east`, `utm_north`** : The UTM bounds of the raw pixel array. This does not reflect any [geometry processing](https://developers.google.com/earth-engine/guides/aef_on_gcs_readme.md.txt#geometry-processing) and includes all pixels whether or not they are valid.
- **`wgs84_west`, `wgs84_south`, `wgs84_east`, `wgs84_north`** : The minimum and maximum longitude and latitude of the WGS84 `geometry`.

## Load a dataset into Earth Engine

NOTE: As a convenience, all sample datasets for Custom Satellite Embeddings will
be added to Google Earth Engine as public ImageCollections using the method
described in the linked notebook guide and will already be de-quantized. The
linked guide can be used by users registering newly delivered Custom Satellite
Embedding datasets as Google Earth Engine ImageCollections.

COGs can be loaded into Earth Engine by either registering them as COG-backed
assets or loading them directly, see the
[Custom Satellite Embeddings Data Access](https://github.com/googlemaps-samples/insights-samples/blob/main/custom_satellite_embeddings/notebooks/ee_data_access/Custom_Satellite_Embeddings_Data_Access.ipynb)
notebook on GitHub for a complete guide to both methods. For a general overview
and comparison of both these methods, see
[Cloud Optimized GeoTIFFs (COGs) in Earth Engine](https://developers.google.com/earth-engine/guides/cog_overview.md.txt#read_cogs_from_cloud_storage).