Get Collection Items

GET

/stac/collections/{collection_id}/items

const url = 'https://example.com/stac/collections/example/items?limit=10&offset=0';
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://example.com/stac/collections/example/items?limit=10&offset=0'

List STAC Items within a collection.

Authorizations

Parameters

Path Parameters

collection_id

required

Collection Id

string

Query Parameters

bbox

Any of:

string
null

string

Bounding box: west,south,east,north

datetime

Any of:

string
null

string

OGC datetime interval

limit

Limit

Maximum number of items returned. Values above 200 are clamped to 200, per the STAC Item Search spec’s clamp-don’t-reject recommendation.

integer

default: 10 >= 1

Maximum number of items returned. Values above 200 are clamped to 200, per the STAC Item Search spec’s clamp-don’t-reject recommendation.

offset

Offset

Legacy offset-based pagination. Phase 269 H-24 lowered the max limit to 200 and recommends keyset cursors via the rel=next link for deep paging.

integer

Legacy offset-based pagination. Phase 269 H-24 lowered the max limit to 200 and recommends keyset cursors via the rel=next link for deep paging.

Responses

200

Successful Response

application/geo+json

StacItemCollectionResponse

Typed OpenAPI representation of a STAC ItemCollection.

object

type

Type

string

default: FeatureCollection

Allowed value: FeatureCollection

features

required

Features

Array<object>

StacItemResponse

A GeoJSON Feature conforming to the STAC Item specification.

object

type

Type

string

default: Feature

Allowed value: Feature

stac_version

required

Stac Version

STAC specification version.

string

stac_extensions

Stac Extensions

STAC extension schema URIs in use.

Array<string>

required

Stable item identifier.

string

geometry

required

Any of:

GeoJSONGeometryCollection

A GeoJSON GeometryCollection (RFC 7946 §3.1.8).

fix(#430 codex r9): carries geometries instead of coordinates, so it needs its own model — only generic-GEOMETRY datasets accept it on write (enforced in the service), and any stored collection must serialize back out on read.

Deliberately NON-recursive (codex r13, refuted): PostGIS cannot round-trip nested collections through the GeoJSON boundary in either direction — ST_GeomFromGeoJSON rejects them on write and ST_AsGeoJSON raises ‘GeoJson: geometry not supported’ on read — so a recursive model could never receive one and would only convert the write-side 422 into a raw database 500. The write schemas add a raw-payload guard for a clear 422.

object

type

required

Type

string

Allowed value: GeometryCollection

geometries

required

Geometries

Array<object>

GeoJSONGeometry

A GeoJSON geometry object (RFC 7946).

object

type

required

Type

string

Allowed values: Point MultiPoint LineString MultiLineString Polygon MultiPolygon

coordinates

required

Coordinates

Array

bbox

Any of:

array

>= 4 items <= 4 items

properties

required

StacItemProperties

Core STAC Item properties plus extension-defined fields.

object

datetime

required

Any of:

string
null

string

start_datetime

Any of:

string
null

string

end_datetime

Any of:

string
null

string

title

Any of:

string
null

string

description

Any of:

string
null

string

key

additional properties

any

links

required

Links

Array<object>

StacLink

A single STAC link object.

object

href

required

Href

Target URL of the link.

string

rel

required

Rel

Link relation type (e.g. ‘self’, ‘root’, ‘parent’, ‘item’, ‘data’).

string

type

Any of:

string
null

string

method

Any of:

string
null

string

assets

required

Assets

object

key

additional properties

StacItemAsset

A STAC asset attached to an Item.

object

href

required

Href

URL of the asset resource.

string

type

Any of:

string
null

string

title

Any of:

string
null

string

description

Any of:

string
null

string

roles

Any of:

Array<string>
null

Array<string>

key

additional properties

any

collection

Any of:

string
null

string

key

additional properties

any

links

required

Links

Array<object>

StacLink

A single STAC link object.

object

href

required

Href

Target URL of the link.

string

rel

required

Rel

Link relation type (e.g. ‘self’, ‘root’, ‘parent’, ‘item’, ‘data’).

string

type

Any of:

string
null

string

method

Any of:

string
null

string

numberMatched

required

Numbermatched

integer

numberReturned

required

Numberreturned

integer

context

required

StacContext

Paging metadata emitted with STAC ItemCollections.

object

limit

required

Limit

integer

returned

required

Returned

integer

matched

required

Matched

integer

key

additional properties

any

key

additional properties

any

Example

{
  "context": {
    "limit": 10,
    "matched": 0,
    "returned": 0
  },
  "features": [],
  "links": [],
  "numberMatched": 0,
  "numberReturned": 0,
  "type": "FeatureCollection"
}

400

Bad request — invalid query parameters or payload

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Unauthenticated — a credential was supplied and could not be resolved (expired, revoked, or malformed). Sending no credential at all is not an error on these operations; they answer anonymously with the public subset. Neither is sending an unresolvable credential alongside a capability that authorizes the request on its own — a valid X-Embed-Token or a valid signed tile template (sig, exp, scope). Those are served and the unrelated credential is ignored.

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Not found

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Too many requests — retry after the advertised interval

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Retry-After

integer

Seconds until the request may be retried

500

Internal server error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Service unavailable — the database could not serve the request

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Privacy Apache 2.0 getgeolens.com