How to Run S2DR

Python Package

Install the gamma-earth-s2dr package, search for imagery, submit a job and download the products from Python, with no GPU needed.

The gamma-earth-s2dr package lets you find imagery, run S2DR3 and download the results from Python. It talks to the Gamma Earth API with your API key, so the processing happens on Gamma Earth servers: you do not need a GPU.

Before You Start

Install

pip install gamma-earth-s2dr

Set your key as an environment variable, or pass it when you create the client:

from gamma_earth_s2dr import Client

client = Client()   # reads GE_API_KEY (and the API address) from the environment
# or: Client(api_url="...", api_key="...")

Keep your key private. The package sends it only to the Gamma Earth API, never prints it and removes it from error messages.

Run a Job

job = client.submit((30.906, 51.394, 30.936, 51.422), "2024-06-15")
files = job.download("out/")
  • The area is lon_min, lat_min, lon_max, lat_max, then the date.
  • submit spends credits. Do not retry it blindly if it fails after the request was sent: the job may exist. Check your jobs first.
  • download waits for the product (usually minutes; the first job after a quiet period is slower), then saves the files.
  • To follow a job you already created: client.job("<job id>").

Find Imagery First

found = client.search(
    bbox=(30.9, 51.39, 30.94, 51.42),
    datetime=("2024-06-01", "2024-06-30"),
    max_clouds=20,
)
found.products   # products you already made
found.scenes     # Sentinel-2 scenes you have not processed yet, with the price

You can also search by product id (ids=[...]) or by tile (tile="36UUB"). A product you already paid for is free to make again, and the search does not list scenes for an area and day you already have a product for.

To process a scene, ask for it and check the price before you confirm:

job = client.process(found.scenes[0])                      # shows the price, spends nothing
job = client.process(found.scenes[0], confirm=True, max_credits=10)
job.download("out/")

Products and Files

Choose what to download with client.download(collection, "out/", assets=["tci"]). Names are ms, tci, irp, ndvi and, for the original-resolution files, names ending in _10m. Older products offer only ms and tci. See Understanding S2DR for what each file is.

After a download, out/collection.json lists the files you downloaded and works offline with any STAC tool, for example pystac.ItemCollection.from_file("out/collection.json").