S2DR Model Knowledge

STAC Collections

How Gamma Earth describes your products as STAC items and collections, and how to read them with the Python package or any STAC tool.

Every product Gamma Earth makes for you is described as a STAC item. STAC (SpatioTemporal Asset Catalog) is an open standard for describing satellite imagery, so the Python package, GIS software and other tools can all read your products without a Gamma Earth specific format.

This article explains the pieces and how to read them. Reading is all it covers: you cannot change or add anything through STAC.

The Pieces

TermWhat it is
ItemOne product. It has the footprint, the image date, the cloud cover and the list of its files. Gamma Earth writes it as item.json, next to the product files.
AssetOne file of a product, for example the true-colour image.
CollectionA group of items. Gamma Earth publishes one for S2DR3 products, called s2dr3.
CatalogThe root that lists the collections.

Your Products

  • One collection, your products. The collection s2dr3 is the same for every user, but it lists only the products you made with your API key. The products of other users never appear in it.

  • One item for each product. The item is named after the product ID (PID). Its assets are the product files:

    AssetWhat it is
    msMultispectral, 10 bands
    tciTrue color
    irpInfrared pseudo-colour image
    ndviVegetation index drawn with a colour scale
    ms_10m, tci_10m, irp_10m, ndvi_10mThe same four products at the original Sentinel-2 resolution (10 m)

    See S2DR Model Knowledge for what the files are.

  • A collection for each job. When you submit a job, the answer carries stac_item and stac_job: the addresses of the product's item and of the job's own collection. The collection is empty while the job runs and holds the product once it is ready.

  • Older products have no item. Products made before STAC was introduced have no item file, so they are not listed in the collection or found by a search. Their files are still available at the address in save_path_S3_TCI.

Read Your Products

With the Python Package

The gamma-earth-s2dr package reads the collection for you: it can list the collection, search it, wait for a job's product and download the assets, and it writes a collection.json of what you downloaded.

Open stac_item or stac_job from the job answer with your API key. Both return STAC documents that any STAC-aware tool can read.

With Any STAC Tool

You can browse the collection with a tool of your own, for example the Python library pystac-client. The address of the catalog is:

https://api.gamma.earth/stac

Send your API key in the X-API-Key header (or as Authorization: Bearer <key>). The key is never put in the web address. The root of the catalog can be opened without a key; the collection, its items and the search need one.

from pystac_client import Client

catalog = Client.open(
    "https://api.gamma.earth/stac",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

search = catalog.search(
    collections=["s2dr3"],
    bbox=(9.30, 50.50, 9.32, 50.52),
    max_items=5,
)
for item in search.items():
    print(item.id, item.datetime, sorted(item.assets))

Search by collections, bbox, intersects, datetime, ids and limit (1 to 100 items a page, 10 by default; the tool follows the next-page links). Restrict the search to s2dr3, as above: a search without a collection can also list Sentinel-2 scenes you have not processed yet, which are not products.

Downloading an asset. An asset address does not hold the file itself. It answers with a redirect to a download address that is valid for 5 minutes. Open the asset address with your key, then follow the redirect without your key: the download address is on another host and must not receive it. Read the asset address again from the item when the 5 minutes have passed.

import requests

href = item.assets["tci"].href
step = requests.get(href, headers={"X-API-Key": "YOUR_API_KEY"}, allow_redirects=False)
file_url = step.headers["Location"]
data = requests.get(file_url)             # no key here

Limits

  • You see only your own products. A product of someone else answers like one that does not exist.
  • A product's footprint is approximate, so a search by area can return a product whose area only comes close to yours.
  • Requests are rate limited. If you get status 429, wait a moment and try again.
  • Reading is all that is supported. To process a Sentinel-2 scene, use the REST API or the Python package.