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

Lists the named render presets, such as true-color, false-color, ndvi, ndwi, moisture and hillshade, with their bands, expression, colour ramp, default collection, accepted collections, cloud-mask settings and zoom range. Presets are the only renders anonymous callers can request.

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

cloudMask

Unified cloud mask settings from schema v1.

object

exclude

Mask classes to drop. Defaults to schema v1 defaultExclude for statistics and time series and to the preset value for tiles.

Array<string>

unique items

Allowed values: nodata saturated_defective cloud cloud_shadow cirrus cloud_adjacent snow_ice water dark_terrain_shadow unclassified clear

scl7

How Sentinel-2 SCL class 7 is treated.

string

default: unclassified

Allowed values: unclassified cloud clear

dilate_m

Buffer in metres around cloud and cloud_shadow on sources without one.

integer

0 <= 600

cloudConfidence

Minimum Landsat QA_PIXEL cloud confidence counted as cloud.

string

default: medium

Allowed values: low medium high

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

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 reflectance stretched from 0 to 0.3, least cloudy scene first.",
      "collection": "sentinel-2-l2a",
      "collections": [
        "sentinel-2-l2a",
        "landsat-ot-l2",
        "landsat-etm-l2",
        "landsat-tm-l2",
        "hls",
        "optical-sr"
      ],
      "bands": [
        "red",
        "green",
        "blue"
      ],
      "rescale": [
        0,
        0.3
      ],
      "harmonize": "offset_removed",
      "mosaickingOrder": "leastCC",
      "maxCloudCoverage": 30,
      "cloudMask": {
        "exclude": [
          "nodata"
        ]
      },
      "defaultWindow": "P30D",
      "minzoom": 8,
      "maxzoom": 14,
      "tileMatrixSets": [
        "WebMercatorQuad",
        "WorldCRS84Quad"
      ],
      "formats": [
        "png",
        "jpg",
        "webp"
      ],
      "links": [
        {
          "href": "https://api.satellitedata.net/v1/presets/true-color",
          "rel": "self",
          "type": "application/json"
        }
      ]
    },
    {
      "id": "ndvi",
      "title": "NDVI",
      "description": "Normalized difference vegetation index from red and nir08, cloud-masked, on a red-yellow-green ramp from -0.2 to 0.9.",
      "collection": "optical-sr",
      "collections": [
        "optical-sr",
        "sentinel-2-l2a",
        "landsat-ot-l2",
        "hls"
      ],
      "bands": [
        "red",
        "nir08"
      ],
      "expression": "(nir08 - red) / (nir08 + red)",
      "rescale": [
        -0.2,
        0.9
      ],
      "colormap": "rdylgn",
      "harmonize": "bandpass_adjusted",
      "mosaickingOrder": "leastCC",
      "maxCloudCoverage": 60,
      "cloudMask": {
        "exclude": [
          "nodata",
          "saturated_defective",
          "cloud",
          "cloud_shadow",
          "cirrus",
          "cloud_adjacent"
        ],
        "scl7": "unclassified",
        "dilate_m": 150
      },
      "defaultWindow": "P30D",
      "minzoom": 8,
      "maxzoom": 14,
      "tileMatrixSets": [
        "WebMercatorQuad",
        "WorldCRS84Quad"
      ],
      "formats": [
        "png",
        "webp"
      ],
      "links": [
        {
          "href": "https://api.satellitedata.net/v1/presets/ndvi",
          "rel": "self",
          "type": "application/json"
        },
        {
          "href": "https://api.satellitedata.net/v1/tiles/ndvi/WebMercatorQuad/tilejson.json",
          "rel": "tiles",
          "type": "application/json",
          "title": "TileJSON"
        },
        {
          "href": "https://api.satellitedata.net/v1/tiles/ndvi/WebMercatorQuad/WMTSCapabilities.xml",
          "rel": "describedby",
          "type": "application/xml",
          "title": "WMTS capabilities"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.satellitedata.net/v1/presets",
      "rel": "self",
      "type": "application/json"
    }
  ]
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

ETag

string

Entity tag; includes the render version.

Example

"r3-9f2c1a"

Cache-Control

string

Caching policy for CloudFront and browsers.

Example

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

429

A per-minute, concurrency, monthly or per-IP limit was hit. Retry-After says when to retry.

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

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

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

RateLimit

string

Remaining units and seconds to reset in the current window (IETF RateLimit header draft).

Example

"units";r=287;t=41

RateLimit-Policy

string

Quota policy of the caller (IETF RateLimit header draft).

Example

"units";q=300;w=60

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

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

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