Render or extract an area

POST

/v1/process

const url = 'https://api.satellitedata.net/v1/process';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'},
  body: '{"input":{"bounds":{"bbox":[0.738,40.711,0.762,40.729]},"data":[{"type":"sentinel-2-l2a","dataFilter":{"timeRange":{"from":"2026-08-29T00:00:00Z","to":"2026-08-29T23:59:59Z"},"maxCloudCoverage":30},"processing":{"units":"REFLECTANCE"}}]},"bands":["red","nir08"],"output":{"width":512,"height":512,"crs":"EPSG:32631","format":"image/tiff","sampleType":"FLOAT32"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.satellitedata.net/v1/process \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "input": { "bounds": { "bbox": [ 0.738, 40.711, 0.762, 40.729 ] }, "data": [ { "type": "sentinel-2-l2a", "dataFilter": { "timeRange": { "from": "2026-08-29T00:00:00Z", "to": "2026-08-29T23:59:59Z" }, "maxCloudCoverage": 30 }, "processing": { "units": "REFLECTANCE" } } ] }, "bands": [ "red", "nir08" ], "output": { "width": 512, "height": 512, "crs": "EPSG:32631", "format": "image/tiff", "sampleType": "FLOAT32" } }'

The Process request mapped onto the download renderer: one data source; input.bounds as a bbox, or a geometry whose bounding box is read; dataFilter.timeRange picks up to 6 scenes in mosaickingOrder (or dataFilter.ids names them); output image/tiff only. GeoTIFFs up to 4 MB come back inline, larger ones answer 303 with a one-hour presigned S3 link. Outputs over 2,500 pixels a side answer 413; use POST /v1/process/jobs for up to 20,000.

Authorizations

ApiKey

Request Body^required

Process request.

application/json

Process request (lean v1): one source, bands by name, GeoTIFF output. preset and expression are not available yet.

object

input

required

Inputs.

object

bounds

required

Area of interest: bbox or geometry, not both.

object

bbox

Bounding box as [west, south, east, north] in CRS84 longitude and latitude, or six numbers with heights.

Array<number>

>= 4 items <= 6 items

geometry

A GeoJSON geometry.

object

type

required

GeoJSON geometry type.

string

Allowed values: Point MultiPoint LineString MultiLineString Polygon MultiPolygon

coordinates

required

GeoJSON coordinates in CRS84 longitude and latitude (RFC 7946).

array

properties

Bounds properties.

object

crs

CRS of bbox or geometry as an OGC URI.

string

default: http://www.opengis.net/def/crs/OGC/1.3/CRS84

data

required

One input collection (no fusion in the lean v1).

Array<object>

>= 1 items <= 1 items

One input collection.

object

type

required

Collection id or alias, for example optical-sr or S2L2A.

string

dataFilter

required

Which scenes feed the request: a timeRange search (up to 6 scenes, in mosaickingOrder) or explicit ids.

object

timeRange

Acquisition time window.

object

from

required

Inclusive start, RFC 3339 UTC.

string format: date-time

required

Inclusive end, RFC 3339 UTC.

string format: date-time

maxCloudCoverage

Maximum scene cloud cover percentage.

number

default: 100 <= 100

mosaickingOrder

Scene order for mosaics.

string

default: mostRecent

Allowed values: mostRecent leastRecent leastCC

ids

Lean extension: item ids to mosaic, first on top, instead of timeRange.

Array<string>

>= 1 items <= 6 items

processing

How values are converted.

object

units

REFLECTANCE (default): float32 physical values (reflectance; kelvin for lwir11). DN: stored integers.

string

Allowed values: REFLECTANCE DN

harmonize

Default offset_removed: Sentinel-2 DN minus the 1000 baseline offset (int16). Equals none for REFLECTANCE and for Landsat.

string

Allowed values: none offset_removed

clipNegative

Clip negative reflectance to 0.

boolean

resampling

Resampling method.

string

default: nearest

Allowed values: nearest

bands

Bands by common name, native name or alias from schema v1; default every spectral band.

Array<string>

output

required

Output size and format.

object

width

Output width in pixels: up to 2,500 on POST /v1/process (413 above), 20,000 on jobs.

integer

>= 1 <= 20000

height

Output height in pixels: up to 2,500 on POST /v1/process (413 above), 20,000 on jobs.

integer

>= 1 <= 20000

resx

Pixel width in CRS units, instead of width.

number

resy

Pixel height in CRS units, instead of height.

number

crs

Output CRS as an EPSG code (EPSG:32631) or OGC URI.

string

default: EPSG:3857

format

Output media type.

string

default: image/tiff

Allowed values: image/tiff

sampleType

Output sample type. FLOAT32 for REFLECTANCE, INT16 for Sentinel-2 DN with offset_removed, UINT16 for stored DN; AUTO or absent picks it.

string

Allowed values: AUTO UINT16 INT16 FLOAT32

Example

{
  "input": {
    "bounds": {
      "bbox": [
        0.738,
        40.711,
        0.762,
        40.729
      ]
    },
    "data": [
      {
        "type": "sentinel-2-l2a",
        "dataFilter": {
          "timeRange": {
            "from": "2026-08-29T00:00:00Z",
            "to": "2026-08-29T23:59:59Z"
          },
          "maxCloudCoverage": 30
        },
        "processing": {
          "units": "REFLECTANCE"
        }
      }
    ]
  },
  "bands": [
    "red",
    "nir08"
  ],
  "output": {
    "width": 512,
    "height": 512,
    "crs": "EPSG:32631",
    "format": "image/tiff",
    "sampleType": "FLOAT32"
  }
}

Responses

200

The GeoTIFF, when it is 4 MB or smaller: tiled, deflate-compressed, one band per requested band, with scale and offset per band.

image/tiff

string

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

X-Attribution

string

Credit lines for the data in the response, separated by semicolons.

Example

Contains modified Copernicus Sentinel data 2026; Landsat data courtesy of the U.S. Geological Survey

303

Output larger than 4 MB: Location is a presigned S3 link valid for one hour; the object expires after a day.

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

X-Attribution

string

Credit lines for the data in the response, separated by semicolons.

Example

Contains modified Copernicus Sentinel data 2026; Landsat data courtesy of the U.S. Geological Survey

Location

string format: uri

CloudFront signed URL of the output in the results bucket.

Example

https://api.satellitedata.net/results/01JQ7Z3M8R5V2W6X9Y0A1B2C3D.tif?Expires=1792055112&Signature=c2lnbmF0dXJl&Key-Pair-Id=K2JCJMDEHXQW5F

400

Malformed body.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "output.width must be an integer from 1 to 2500.",
  "instance": "/v1/process",
  "code": "invalid-body",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "errors": [
    {
      "pointer": "/output/width",
      "detail": "must be <= 2500"
    }
  ]
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

401

The X-API-Key header is missing or the key is unknown, disabled or not on this API’s usage plan.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/invalid-key",
  "title": "Invalid or missing credentials",
  "status": 401,
  "detail": "Send a valid key in the X-API-Key header.",
  "instance": "/v1/search",
  "code": "invalid-key",
  "requestId": "c1d2e3f4-0000-4a5b-8c9d-0123456789ab"
}

Headers

WWW-Authenticate

string

Challenge naming the accepted scheme.

Example

ApiKey header="X-API-Key"

413

A size cap was exceeded.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/output-too-large",
  "title": "Output too large",
  "status": 413,
  "detail": "Output 3000 x 3000 pixels is over the 2500 pixel limit per side for synchronous process; POST /v1/process/jobs takes up to 20000.",
  "instance": "/v1/process",
  "code": "output-too-large",
  "requestId": "c1d2e3f4-0000-4a5b-8c9d-0123456789ab",
  "limits": {
    "maxOutputWidth": 2500,
    "maxOutputHeight": 2500,
    "requestedWidth": 3000,
    "requestedHeight": 3000
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

422

Valid JSON the lean v1 cannot serve: an unknown band, or units or harmonization it does not offer.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/unknown-band",
  "title": "Unknown band",
  "status": 422,
  "detail": "landsat-ot-l2 has no band 'nir'; cross-sensor NIR is nir08. Close names: ['nir08']. The full list is in /v1/schema.",
  "instance": "/v1/process",
  "code": "unknown-band",
  "requestId": "c1d2e3f4-0000-4a5b-8c9d-0123456789ab",
  "errors": [
    {
      "pointer": "/bands/1",
      "detail": "unknown band"
    }
  ]
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

429

The key’s rate limit or monthly quota (usage plan satdata-personal) was hit.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "This key spent 300 of its 300 units in the current minute.",
  "instance": "/v1/process",
  "code": "rate-limited",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 17,
  "limits": {
    "unitsPerMinute": 300,
    "unitsSpentThisMinute": 300
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

500

An unexpected server error. No units are charged.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/internal",
  "title": "Internal error",
  "status": 500,
  "detail": "The request failed on our side and was logged. No units were charged.",
  "instance": "/v1/process",
  "code": "internal",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

503

Earth Search or the renderer is unavailable.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/upstream-unavailable",
  "title": "Upstream unavailable",
  "status": 503,
  "detail": "Earth Search did not answer: ReadTimeout",
  "instance": "/v1/process",
  "code": "upstream-unavailable",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 120
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

504

The render did not finish within the 29-second API Gateway limit. No units are charged.

application/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/render-timeout",
  "title": "Render timed out",
  "status": 504,
  "detail": "The render read 41 scenes and did not finish in 29 seconds. Narrow the time range or lower the output size.",
  "instance": "/v1/process",
  "code": "render-timeout",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Render or extract an area

Authorizations

Request Bodyrequired

Example

Responses

200

Headers

Example

Example

303

Headers

Example

Example

Example

400

Example

Headers

Example

401

Example

Headers

Example

413

Example

Headers

Example

422

Example

Headers

Example

429

Example

Headers

Example

Example

500

Example

Headers

Example

503

Example

Headers

Example

Example

504

Example

Headers

Example

Request Body^required