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
- Python 3.9 or later.
- A Gamma Earth API key and credits. See API Access & Keys to find your key and How Credits Work for prices.
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. submitspends credits. Do not retry it blindly if it fails after the request was sent: the job may exist. Check your jobs first.downloadwaits 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").