Collection with bands, units, extents and attribution

GET

/v1/collections/{collectionId}

const url = 'https://api.satellitedata.net/v1/collections/sentinel-2-l2a';
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/collections/sentinel-2-l2a

One collection by id or alias. An alias answers 200 with the canonical document and a Content-Location header naming the canonical URL.

Parameters

Path Parameters

collectionId

required

string

/^[A-Za-z0-9_.-]+$/

Collection id or alias without a slash, for example sentinel-2-l2a or S2L2A.

Example

sentinel-2-l2a

Responses

200

The collection; the band table is shortened to three bands.

application/json

STAC collection with the schema v1 band table, units and attribution.

object

type

required

Always Collection.

string

Allowed value: Collection

stac_version

required

STAC version.

string

stac_extensions

STAC extension schema URIs.

Array<string>

required

Canonical collection id.

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

title

Collection title.

string

description

required

Collection description.

string

keywords

Keywords.

Array<string>

license

required

SPDX id, or “other” with a license link.

string

providers

Data providers.

Array<object>

Provider.

object

name

required

Provider name.

string

roles

Roles.

Array<string>

Allowed values: licensor producer processor host

url

Provider URL.

string format: uri

extent

required

Extents measured from the index.

object

spatial

required

Spatial extent.

object

bbox

required

Overall bbox first, then optional sub-boxes.

Array<Array<number>>

temporal

required

Temporal extent.

object

interval

required

Intervals; an open end is null.

Array<Array<string | null>>

summaries

STAC summaries, such as platform and eo:cloud_cover ranges.

object

key

additional properties

any

bands

Band table from schema v1 (STAC 1.1 bands field). Empty on optical-sr, which lists common names in sdn:bands_common.

Array<object>

One band, from the schema v1 crosswalk.

object

name

required

Native band name, unique within the collection, for example B8A or SR_B5.

string

common_name

STAC eo common name, the cross-sensor key, for example nir08.

string

description

Band description.

string | null

aliases

Other names that resolve to this band within the collection.

Array<string>

center_wavelength

Centre wavelength in micrometres.

number | null

full_width_half_max

Full width at half maximum in micrometres.

number | null

gsd

Native ground sample distance in metres.

number

data_type

Stored data type.

string

Allowed values: uint8 uint16 int16 float32

scale

Raster:scale; value = scale x DN + offset.

number

offset

Raster:offset for the newest product; see offset_rule when it depends on the item.

number

offset_rule

How the offset is chosen per item, when it is not constant.

string

nodata

Stored nodata value.

number | null

unit

Default unit id from schema v1.

string

cross_sensor

True when the band resolves on optical-sr.

boolean

notes

Notes on the band, such as naming conflicts between catalogs.

string

sdn:aliases

Aliases from schema v1.

Array<object>

Collection alias.

object

required

Alias id accepted wherever a collection id is accepted.

string

source

required

Where the alias comes from, such as Sentinel Hub or Earth Search.

string

group

Alias group when one upstream id spans several collections.

string

filter

CQL2 text filter that the alias implies.

string

sdn:attribution

Exact credit line to show with any output; responses replace {years} with acquisition years.

string

sdn:units

Units the collection can return.

Array<string>

Allowed values: REFLECTANCE DN KELVIN CELSIUS LINEAR_POWER DB METERS DEGREES FRACTION

sdn:default_units

Unit used when the request does not choose one.

string

Allowed values: REFLECTANCE DN KELVIN CELSIUS LINEAR_POWER DB METERS DEGREES FRACTION

sdn:harmonize_levels

Harmonization levels the collection supports.

Array<string>

Allowed values: none offset_removed bandpass_adjusted nbar

sdn:default_harmonize

Harmonization level used when the request does not choose one.

string

Allowed values: none offset_removed bandpass_adjusted nbar

sdn:pseudo_bands

Derived bands such as mask, mask_class and dataMask.

Array<string>

sdn:mask_source

Cloud-mask source.

string

Allowed values: scl qa_pixel fmask s2cloudless none

sdn:mask_capabilities

Mask classes the source can detect. A class missing here is not detectable, not absent.

Array<string>

sdn:virtual

True for optical-sr, which searches its member collections.

boolean

sdn:members

Member collections of a virtual 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

sdn:bands_common

Common band names that resolve on a virtual collection.

Array<string>

sdn:zoom

Tile zoom range.

object

min

required

Lowest zoom served from the full archive.

integer

max

required

Highest zoom served.

integer

links

required

Links, including items, queryables, license and the schema.

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

{
  "type": "Collection",
  "id": "sentinel-2-l2a",
  "providers": [
    {
      "roles": [
        "licensor"
      ]
    }
  ],
  "bands": [
    {
      "data_type": "uint8"
    }
  ],
  "sdn:units": [
    "REFLECTANCE"
  ],
  "sdn:default_units": "REFLECTANCE",
  "sdn:harmonize_levels": [
    "none"
  ],
  "sdn:default_harmonize": "none",
  "sdn:mask_source": "scl",
  "sdn:members": [
    "sentinel-2-l2a"
  ],
  "links": [
    {
      "method": "GET"
    }
  ]
}

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

Content-Location

string

Canonical URL when the request used an alias.

Example

https://api.satellitedata.net/v1/collections/sentinel-2-l2a

404

No resource has this id.

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

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