Skip to content
satellitedata.net

STAC item search, cql2-text

GET
/v1/search
curl --request GET \
  --url 'https://api.satellitedata.net/v1/search?collections=sentinel-2-l2a&ids=S2C_T15TVK_20260712T171233_L2A&bbox=-93.3%2C44.9%2C-93.2%2C45&intersects=%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-93.25%2C44.95%5D%7D&datetime=2026-06-01T00%3A00%3A00Z%2F2026-08-31T23%3A59%3A59Z&limit=10&token=2026-08-29T10%3A56%3A03.794000Z%2CS2A_T31TCF_20260829T105044_L2A%2Csentinel-2-c1-l2a&sortby=%2Bproperties.eo%3Acloud_cover&fields=id%2Cproperties.datetime%2Cproperties.eo%3Acloud_cover&query=%7B%22eo%3Acloud_cover%22%3A%7B%22lte%22%3A20%7D%7D' \
  --header 'X-API-Key: <X-API-Key>'

STAC search on Earth Search. collections take ids or aliases (default both lean collections); cloud filter through the query extension; paging links carry token.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
collections
Array<string>

Collection ids or aliases.

Example 

?collections=sentinel-2-l2a
ids
Array<string>

Item ids.

Example 

?ids=S2C_T15TVK_20260712T171233_L2A
bbox
Array<number>
>= 4 items <= 6 items

West, south, east, north in CRS84.

Example 

?bbox=-93.3,44.9,-93.2,45
intersects
string

GeoJSON geometry as URL-encoded JSON text; mutually exclusive with bbox.

Example 

{"type":"Point","coordinates":[-93.25,44.95]}
datetime
string

RFC 3339 instant or interval (dates alone are allowed); an open end is written .. . Tiles default to the last 30 days.

Example 

2026-06-01T00:00:00Z/2026-08-31T23:59:59Z
limit
integer
default: 10 >= 1 <= 1000

Page size.

Example 

10
token
string

Opaque paging token from a next or prev link.

Example 

2026-08-29T10:56:03.794000Z,S2A_T31TCF_20260829T105044_L2A,sentinel-2-c1-l2a
sortby
string

Comma-separated sort fields, each prefixed + or -. Default -datetime.

Example 

+properties.eo:cloud_cover
fields
string

Fields extension: comma-separated fields, prefixed - to exclude.

Example 

id,properties.datetime,properties.eo:cloud_cover
query
string

STAC query extension as URL-encoded JSON, for example {“eo:cloud_cover”:{“lte”:20}}.

Example 

{"eo:cloud_cover":{"lte":20}}

Responses

Section titled “Responses”

200

Section titled “200”

One page of matching items.

Media typeapplication/geo+json

STAC item collection, one page of results.

object
type
required

Always FeatureCollection.

string
Allowed value: FeatureCollection
features
required

Matching items, at most limit.

Array<object>

STAC item.

object
type
required

Always Feature.

string
Allowed value: Feature
stac_version
required

STAC version.

string
stac_extensions

Extensions.

Array<string>
id
required

Native upstream item id.

string
collection

Collection id.

string
geometry
required
One of:

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
bbox

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

Array<number>
>= 4 items <= 6 items
properties
required

Item properties. Any property listed by queryables can appear; the common ones are named here.

object
datetime
required

Acquisition time, UTC.

string | null format: date-time
platform

Normalized lowercase platform, for example sentinel-2c or landsat-9.

string
constellation

Constellation.

string
instruments

Instruments.

Array<string>
eo:cloud_cover

Scene cloud cover percentage from the producer.

number
<= 100
s2:mgrs_tile

Sentinel-2 MGRS tile.

string
s2:processing_baseline

Sentinel-2 processing baseline, which decides the DN offset.

string
landsat:wrs_path

Landsat WRS-2 path.

string
landsat:wrs_row

Landsat WRS-2 row.

string
sdn:source_collection

Native collection of an item returned through optical-sr.

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:mask_source

Cloud-mask source for the item.

string
Allowed values: scl qa_pixel fmask s2cloudless none
sdn:mask_capabilities

Mask classes the item can detect.

Array<string>
sdn:harmonization

Harmonization level that applies to this item at the collection default.

string
Allowed values: none offset_removed bandpass_adjusted nbar
key
additional properties
any
assets
required

Assets keyed by native band name or role.

object
key
additional properties

STAC asset. href points at the public upstream COG.

object
href
required

Asset URL.

string format: uri
type

Media type.

string
title

Title.

string
roles

Asset roles such as data, overview or cloud.

Array<string>
sdn:band

Band name the asset holds, when it holds one band.

string
key
additional properties
any
links
required

Links, including self, collection and preview.

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

Paging links: next and prev carry the token.

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
numberMatched

Total matches, present when under 10,000.

integer
numberReturned

Items in this page.

integer

Example 

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point"
      },
      "properties": {
        "sdn:source_collection": "sentinel-2-l2a",
        "sdn:mask_source": "scl",
        "sdn:harmonization": "none"
      },
      "links": [
        {
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "method": "GET"
    }
  ]
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D

400

Section titled “400”

The request is malformed or a parameter is invalid.

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/invalid-parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "bbox must have 4 or 6 numbers; got 3.",
  "instance": "/v1/search",
  "code": "invalid-parameter",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "errors": [
    {
      "pointer": "bbox",
      "detail": "expected 4 or 6 numbers"
    }
  ]
}

Headers

Section titled “Headers”
X-Request-Id
string

Request id for support and logs.

Example 
01JQ7Z3M8R5V2W6X9Y0A1B2C3D

401

Section titled “401”

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

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

Section titled “Headers”
WWW-Authenticate
string

Challenge naming the accepted scheme.

Example 
ApiKey header="X-API-Key"

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

503

Section titled “503”

Earth Search or the renderer is unavailable.

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

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