List render presets

GET

/v1/presets

const url = 'https://api.satellitedata.net/v1/presets';
const options = {method: 'GET'};

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

curl --request GET \
  --url https://api.satellitedata.net/v1/presets

True-color, false-color and ndvi, each with per-collection band recipes in sdn:recipes.

Responses

200

Presets; the example is shortened to two.

application/json

Preset list.

object

presets

required

Presets.

Array<object>

Render preset.

object

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

links

required

Links.

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

Example

{
  "presets": [
    {
      "id": "true-color",
      "title": "True colour",
      "description": "Red, green and blue, about 0 to 0.3 reflectance, least cloudy scene first. Sentinel-2 uses its 8-bit visual (TCI) asset.",
      "collection": "sentinel-2-l2a",
      "collections": [
        "sentinel-2-l2a",
        "landsat-ot-l2"
      ],
      "bands": [
        "red",
        "green",
        "blue"
      ],
      "rescale": [
        0,
        0.3
      ],
      "harmonize": "offset_removed",
      "mosaickingOrder": "leastCC",
      "maxCloudCoverage": 30,
      "defaultWindow": "P30D",
      "minzoom": 8,
      "maxzoom": 15,
      "tileMatrixSets": [
        "WebMercatorQuad",
        "WorldCRS84Quad"
      ],
      "formats": [
        "png",
        "jpg",
        "webp"
      ],
      "sdn:recipes": {
        "sentinel-2-l2a": {
          "assets": [
            "visual"
          ],
          "minzoom": 8,
          "maxzoom": 15
        },
        "landsat-ot-l2": {
          "assets": [
            "red",
            "green",
            "blue"
          ],
          "rescale": [
            7273,
            18182
          ],
          "minzoom": 7,
          "maxzoom": 14
        }
      },
      "links": [
        {
          "rel": "self",
          "type": "application/json",
          "href": "https://api.satellitedata.net/v1/presets/true-color"
        },
        {
          "rel": "tiles",
          "type": "application/json",
          "title": "TileJSON",
          "href": "https://api.satellitedata.net/v1/tiles/true-color/WebMercatorQuad/tilejson.json"
        }
      ]
    },
    {
      "id": "false-color",
      "title": "False colour (vegetation red)",
      "description": "Near infrared, red and green as red, green and blue, 0 to 0.4 reflectance, least cloudy scene first.",
      "collection": "sentinel-2-l2a",
      "collections": [
        "sentinel-2-l2a",
        "landsat-ot-l2"
      ],
      "bands": [
        "nir",
        "red",
        "green"
      ],
      "rescale": [
        0,
        0.4
      ],
      "harmonize": "offset_removed",
      "mosaickingOrder": "leastCC",
      "maxCloudCoverage": 30,
      "defaultWindow": "P30D",
      "minzoom": 8,
      "maxzoom": 15,
      "tileMatrixSets": [
        "WebMercatorQuad",
        "WorldCRS84Quad"
      ],
      "formats": [
        "png",
        "jpg",
        "webp"
      ],
      "sdn:recipes": {
        "sentinel-2-l2a": {
          "assets": [
            "nir",
            "red",
            "green"
          ],
          "rescale": [
            1000,
            5000
          ],
          "minzoom": 8,
          "maxzoom": 15
        },
        "landsat-ot-l2": {
          "assets": [
            "nir08",
            "red",
            "green"
          ],
          "rescale": [
            7273,
            21818
          ],
          "minzoom": 7,
          "maxzoom": 14
        }
      },
      "links": [
        {
          "rel": "self",
          "type": "application/json",
          "href": "https://api.satellitedata.net/v1/presets/false-color"
        },
        {
          "rel": "tiles",
          "type": "application/json",
          "title": "TileJSON",
          "href": "https://api.satellitedata.net/v1/tiles/false-color/WebMercatorQuad/tilejson.json"
        }
      ]
    },
    {
      "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"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "type": "application/json",
      "href": "https://api.satellitedata.net/v1/presets"
    }
  ]
}

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

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