Skip to content
satellitedata.net

One render preset

GET
/v1/presets/{presetId}
curl --request GET \
  --url https://api.satellitedata.net/v1/presets/ndvi

One preset with its per-collection band recipes.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
presetId
required
string
/^[a-z0-9-]+$/

Render preset id from GET /v1/presets.

Example 

ndvi

Responses

Section titled “Responses”

200

Section titled “200”

The preset.

Media typeapplication/json

Render preset.

object
id
required

Preset id.

string
title
required

Title.

string
description

What the preset shows.

string
collection
required

Default collection.

string
Allowed values: sentinel-2-l2a dem landsat-ot-l2 landsat-etm-l2 landsat-tm-l2 hls optical-sr sentinel-1-rtc sentinel-2-l1c landsat-ot-l1 landsat-etm-l1 landsat-tm-l1 landsat-mss-l1
collections

Collections the preset accepts through ?collection=.

Array<string>
Allowed values: sentinel-2-l2a dem landsat-ot-l2 landsat-etm-l2 landsat-tm-l2 hls optical-sr sentinel-1-rtc sentinel-2-l1c landsat-ot-l1 landsat-etm-l1 landsat-tm-l1 landsat-mss-l1
bands
required

Bands read, by common name.

Array<string>
expression

Band math, when the preset is an index.

string
rescale

Value range mapped to 0-255.

Array<number>
>= 2 items <= 2 items
colormap

Named colormap for one-band presets.

string
harmonize

Harmonization level.

string
Allowed values: none offset_removed bandpass_adjusted nbar
mosaickingOrder

Scene order.

string
Allowed values: mostRecent leastRecent leastCC
maxCloudCoverage

Scene cloud cover ceiling.

number
defaultWindow

Default time window as an ISO 8601 duration ending now, when ?datetime= is absent.

string
minzoom
required

Lowest zoom.

integer
maxzoom
required

Highest zoom; deeper requests fail at the edge with 400.

integer
tileMatrixSets

Tile matrix sets.

Array<string>
Allowed values: WebMercatorQuad WorldCRS84Quad
formats

Tile formats.

Array<string>
Allowed values: png jpg webp
links

Links to TileJSON and WMTS.

Array<object>

A STAC and OGC API link object.

object
href
required

Link target.

string format: uri
rel
required

Relation type, such as self, root, parent, next, prev, items, queryables, tiles or license.

string
type

Media type of the target.

string
title

Human-readable title.

string
method

HTTP method for the link, GET unless stated. Paging POST /v1/search uses POST.

string
Allowed values: GET POST
body

Request body to send with a POST link, used for the next page of POST /v1/search.

object
key
additional properties
any
merge

When true the client merges body into the previous request body.

boolean
sdn:recipes

Per-collection render recipe: Earth Search asset keys, an expression over b1, b2 in asset order, the DN stretch, the colormap and the zoom range.

object
key
additional properties
object
assets
required

Earth Search asset keys, in band order.

Array<string>
expression

Rio-tiler expression over b1, b2, …

string
rescale

Stored DN mapped to 0-255.

Array<number>
>= 2 items <= 2 items
colormap

Named colormap.

string
minzoom

Lowest zoom for this collection.

integer
maxzoom

Highest zoom for this collection.

integer

Example 

{
  "id": "ndvi",
  "title": "NDVI",
  "description": "Normalized difference vegetation index from reflectance (the Collection 1 offset removed), -0.2 to 0.8 on a red-yellow-green ramp. Sentinel-2 uses the 10 m nir band (B08), Landsat nir08.",
  "collection": "sentinel-2-l2a",
  "collections": [
    "sentinel-2-l2a",
    "landsat-ot-l2"
  ],
  "bands": [
    "red",
    "nir"
  ],
  "expression": "(nir - red) / (nir + red)",
  "rescale": [
    -0.2,
    0.8
  ],
  "colormap": "rdylgn",
  "harmonize": "offset_removed",
  "mosaickingOrder": "leastCC",
  "maxCloudCoverage": 60,
  "defaultWindow": "P30D",
  "minzoom": 8,
  "maxzoom": 15,
  "tileMatrixSets": [
    "WebMercatorQuad",
    "WorldCRS84Quad"
  ],
  "formats": [
    "png",
    "webp"
  ],
  "sdn:recipes": {
    "sentinel-2-l2a": {
      "assets": [
        "nir",
        "red"
      ],
      "expression": "(b1-b2)/(b1+b2-2000)",
      "rescale": [
        -0.2,
        0.8
      ],
      "colormap": "rdylgn",
      "minzoom": 8,
      "maxzoom": 15
    },
    "landsat-ot-l2": {
      "assets": [
        "nir08",
        "red"
      ],
      "expression": "(b1-b2)/(b1+b2-14545.45)",
      "rescale": [
        -0.2,
        0.8
      ],
      "colormap": "rdylgn",
      "minzoom": 7,
      "maxzoom": 14
    }
  },
  "links": [
    {
      "rel": "self",
      "type": "application/json",
      "href": "https://api.satellitedata.net/v1/presets/ndvi"
    },
    {
      "rel": "tiles",
      "type": "application/json",
      "title": "TileJSON",
      "href": "https://api.satellitedata.net/v1/tiles/ndvi/WebMercatorQuad/tilejson.json"
    }
  ]
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D
Cache-Control
string

Caching policy for CloudFront and browsers.

Example 
public, max-age=3600, s-maxage=2592000, stale-if-error=604800

404

Section titled “404”

No resource has this id.

Media typeapplication/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/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No item S2C_T15TVK_20260714T170911_L2X in collection sentinel-2-l2a.",
  "instance": "/v1/collections/sentinel-2-l2a/items/S2C_T15TVK_20260714T170911_L2X",
  "code": "not-found",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D"
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D

429

Section titled “429”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D
Retry-After
integer

Seconds to wait before retrying.

Example 
17

500

Section titled “500”

An unexpected server error. No units are charged.

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D