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
| Term | What it is |
|---|---|
| Item | One 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. |
| Asset | One file of a product, for example the true-colour image. |
| Collection | A group of items. Gamma Earth publishes one for S2DR3 products, called s2dr3. |
| Catalog | The root that lists the collections. |
Your Products
-
One collection, your products. The collection
s2dr3is 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:
Asset What 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_itemandstac_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.
With the Links in a Job Answer
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.