API/SDK

API Latest Release Version 1.0

Migrate to the AWS-hosted RISC API, then submit S2DR3 processing jobs, check job state, and locate generated outputs.

The RISC API lets you submit asynchronous S2DR3 processing jobs. A job submission returns metadata immediately. The generated products appear in the corresponding storage location after processing.

Before You Start

For instructions on how to generate your API key, see API Access & Keys.

Call the API at:

https://api.gamma.earth/jobs/{API_KEY}

Replace {API_KEY} with your API key. Every example below uses this endpoint.

Migrating from the previous endpoint

Gamma Earth is migrating the API from Google Cloud to AWS, to improve stability and speed. https://api.gamma.earth/jobs/{API_KEY} is the address that comes out of that move.

If you have an existing integration that posts to

https://s2dr3-job-20250428-862134799361.europe-west1.run.app/{USER_ID}

point it at https://api.gamma.earth/jobs/{API_KEY} instead, using the API key from your portal in place of the user ID.

The migration changes the endpoint and the credential. Job state checks and output storage work exactly as before.

Submit a Job

Endpoint:

https://api.gamma.earth/jobs/{API_KEY}

Method:

POST

Example payload:

{
  "date": "2023-05-01",
  "date_range": "7",
  "aoi": "19.93 49.28 20.00 49.35"
}

Request Parameters

Parameter	Required	Description
`date`	Yes	Exact Sentinel-2 scene date. The request fails if the scene does not exist.
`date_range`	No	Number of days back from the target date to search.
`aoi`	Yes	Bounding box for the area of interest in `minx miny maxx maxy` order. The source states the AOI should not exceed 150 km2 / a 12x12 km bounding box.
`max_clouds`	No	Maximum cloud cover allowed in the date search.
`geojson`	No	Input GeoJSON file with AOI polygons.
`mgrs`	No	MGRS tile index.
`iso`	No	2-digit ISO country code.
`NM`	No	MGRS subsubtile indices on the 9x9 grid.
`UV`	No	MGRS subtile indices on the 3x3 grid.
`bands_out`	No	Spectral bands to generate in Sentinel-2 format.

Options

Parameter	Required	Description
`cogs`	No	Generate COG outputs for TCI, NDVI, and IRP.
`force`	No	Force re-processing of existing products.
`get_tile`	No	Force downloading the entire Sentinel-2 MGRS tile.

Example Response

The API returns job metadata, not the processed data itself.

{
  "uid": "u28f61076",
  "job_id": "a3781528-90c4-11f1",
  "date": "20230815",
  "MGRS": "36UUB",
  "ISO": "UA",
  "aoi": "30.842 51.394 30.872 51.422",
  "sdk": false,
  "save_path_S3_TCI": "s3://s2dr3-output/UA/T36UUB/T36UUB-56afc34a2-20230815/S2L2Ax10_T36UUB-56afc34a2-20230815_TCI.tif",
  "date_range": "7",
  "sid": "56afc34a2",
  "pid": "T36UUB-56afc34a2-20230815",
  "no_bands": "10",
  "make_preview": "true"
}

Important response fields:

Field	Description
`job_id`	Identifier used to check processing state.
`save_path_S3_TCI`	S3 path for the super-resolved true-color dataset. Download your results from here.
`pid`	Product identifier for the generated scene.

Check Job State

Append the job_id from the submission response to your endpoint:

https://api.gamma.earth/jobs/{API_KEY}/{job_id}

Method:

GET

Example response:

{"job_id": "e26bb408-d330-11ef", "state": "completed"}

Download Outputs

Download your results from save_path_S3_TCI. The response returns the S3 path for the true-color product, but the same S3 directory holds every product generated for the job. Swap the filename to fetch the others, using the job's pid:

Filename	Product	Resolution
`S2L2A_<pid>_TCI.tif`	True color	Sentinel-2 source
`S2L2A_<pid>_MS.tif`	Multispectral	Sentinel-2 source
`S2L2A_<pid>_NDVI.tif`	NDVI	Sentinel-2 source
`S2L2A_<pid>_IRP.tif`	Infrared pseudo-color	Sentinel-2 source
`S2L2Ax10_<pid>_TCI.tif`	True color	Super-resolved (x10)
`S2L2Ax10_<pid>_MS.tif`	Multispectral	Super-resolved (x10)
`S2L2Ax10_<pid>_NDVI.tif`	NDVI	Super-resolved (x10)
`S2L2Ax10_<pid>_IRP.tif`	Infrared pseudo-color	Super-resolved (x10)

Changelog

With the 1.0 release, the API has migrated from GCP to AWS and can now accommodate a large number of parallel processes. Gamma Earth has tested up to 2,200 simultaneous jobs, and believes the actual limit is much higher.

The following were introduced in the earlier 0.2 release version and are still current:

Parameter date_range: number of days back from the target date to search.
Parameter max_clouds: maximum cloud cover allowed in the date search.
Option cogs: generate COG outputs for TCI, NDVI, and IRP.