Detailed STAC item search

Search for specific STAC items.


Overview

If you want to search for STAC items among all collections, make a detailed search request using CQL2 filters.

To get a list of fields that can be used as search filters, call the /v2/assets/stac/queryables endpoint.

Request

GET /v2/assets/stac/queryables HTTP/1.1
Host: api.up42.com
Authorization: Bearer {token}

Response


See response example
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://api.up42.com/v2/assets/stac/queryables",
  "type": "object",
  "title": "STAC Storage Queryables",
  "description": "Queryables for searching STAC Storage.",
  "properties": {
    "datetime": {
      "title": "datetime",
      "description": "Date and time the feature was captured",
      "type": "timestamp"
    },
    "workspace_id": {
      "title": "workspace_id",
      "description": "UP42 Workspace Id",
      "type": "string"
    },
    "asset_id": {
      "title": "asset_id",
      "description": "UP42 Asset Id",
      "type": "string"
    },
    "tags": {
      "title": "tags",
      "description": "UP42 Asset Tags",
      "type": "array"
    },
    "eo:cloud_cover": {
      "title": "eo:cloud_cover",
      "description": "Cloud Coverage",
      "type": "float"
    },
    "cloud_cover": {
      "title": "cloud_cover",
      "description": "Cloud Coverage (Deprecated, will be removed in November 2023. Please use eo:cloud_cover instead)",
      "type": "float"
    },
    "constellation": {
      "title": "constellation",
      "description": "Platform Constellation",
      "type": "string"
    },
    "gsd": {
      "title": "gsd",
      "description": "Ground Sampling Distance",
      "type": "float"
    },
    "title": {
      "title": "title",
      "description": "User Title",
      "type": "string"
    },
    "collection_name": {
      "title": "collection_name",
      "description": "UP42 Collection Name",
      "type": "string"
    },
    "order_id": {
      "title": "order_id",
      "description": "UP42 Order Id",
      "type": "string"
    },
    "geometry": {
        "title": "geometry",
        "description": "Geometry of the STAC item",
        "type": "geometry"
    },
    "id": {
        "title": "id",
        "description": "id of the STAC item",
        "type": "string"
    },
    "collection": {
        "title": "collection",
        "description": "id of the parent collection",
        "type": "string"
    }
  }
}

ParameterOverview
$schemastring
The schema of the response.
$idstring
The URL of the endpoint.
typestring
The type of resource.
titlestring
The title of the endpoint.
descriptionstring
The description of the endpoint.
propertiesobject
A list of queryable properties to use as search filters.
Parameters of the properties object
datetimeobject
Search by date and time the STAC item was acquired by the provider.
workspace_idobject
Search by workspace ID.
asset_idobject
Search by UP42 asset ID.
tagsobject
Search by UP42 asset tags.
eo:cloud_coverobject
Search by cloud coverage.
constellationobject
Search by constellation name.
cloud_coverobject
Search by cloud coverage.
gsdobject
Search by ground sample distance.
titleobject
Search by UP42 asset title.
collection_nameobject
Search by geospatial collection name.
order_idobject
Search by order ID.
geometrygeometry
Search by STAC item geometry.
idstring
Search by STAC item ID.
collectionstring
Search by STAC collection ID.

Search for specific STAC items

To make a detailed search request to find specific STAC items in your storage, call the /v2/assets/stac/search endpoint and specify search parameters in the request body.

You can also search for all STAC items in a STAC collection instead.

Request

POST /v2/assets/stac/search HTTP/1.1
Host: api.up42.com
Content-Type: application/json
Authorization: Bearer {token}

Search by UP42 asset ID and cloud coverage
{
  "filter": {
    "args": [
      {
        "args": [
          {
            "property": "asset_id"
          },
          "b5b3d061-33c1-445d-8a44-8132615fb9a5"
        ],
        "op": "="
      },
      {
        "args": [
          {
            "property": "eo:cloud_cover"
          },
          20.0
        ],
        "op": "<"
      }
    ],
    "op": "and"
  }
}

Search by time interval and bounding box AOI
{
  "datetime": "2022-02-12T00:00:00Z/2022-12-09T12:31:12Z",
  "bbox": [52.45, 13.35, 52.51, 13.42]
}

Search by time interval and intersecting AOI
{
  "datetime": "2021-01-12T00:00:00Z/2022-12-18T12:31:12Z",
  "intersects": {
    "type": "Point",
    "coordinates": [32.613, 46.641]
  }
}

ParameterOverview
bboxarray of floats
Search for STAC items that intersect this bounding box. Use only if intersects isn't specified.
intersectsobject
Search for STAC items that intersect the provided geometry. Use only if bbox isn't specified.
intersects.
coordinates
array of arrays / required if
Required if intersects is specified.
Coordinates for intersects.
intersects.typestring / required if
Required if intersects is spefified.
Search by STAC item AOI. The allowed geometry types:
  • Point
  • MultiPoint
  • LineString
  • MultiLineString
  • Polygon
  • MultiPolygon
collectionsarray of strings
Search for STAC items in the specified STAC collections.
datetimestring
Search for STAC items that have a temporal property that intersects the datetime value in the RFC 3339 format. You can search for a specific date and time, or for a closed or an open date interval. Express open intervals using double-dots.

Examples:
  • A timestamp: "2018-02-12T23:20:50Z"
  • A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
  • Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
filterobject
A CQL2 filter.
filter.argsarray of objects
Arguments inside of a CQL2 filter.
filter.opstring
Operators inside of a CQL2 filter.
filter-langstring
The CQL filter encoding the value used in filter. The only supported value is cql2-json.
idsarray of strings
Search for specific STAC items by their IDs.
limitinteger
The number of STAC items on a results page. The default value is 10.
sortbyarray of strings
A results sorting method that arranges elements in ascending or descending order based on a chosen field.
sortby.directionstring / required if
Required if sortby.field is specified.
An order of sorting. The allowed values: asc, desc. The default value is ascending.
sortby.fieldstring / required if
Required if sortby.direction is specified.
A field to use for sorting.
tokenstring
Search for STAC items before or after the specified one.

Response

The response contains a list of STAC items that match search criteria.

See response example
{
  "links": [
    {
      "href": "https://api.up42.com/v2/assets/stac/",
      "rel": "root",
      "type": "application/json"
    },
    {
      "href": "https://api.up42.com/v2/assets/stac/",
      "rel": "parent",
      "type": "application/json"
    },
    {
      "href": "https://api.up42.com/v2/assets/stac/search",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://api.up42.com/v2/assets/stac/search",
      "rel": "next",
      "type": "application/json",
      "body": {
        "bbox": [52.45, 13.35, 52.51, 13.42],
        "filter": {},
        "token": "next:3eeff7c6-a1c9-4340-b484-601f689c30bf"
      },
      "method": "POST"
    }
  ],
  "type": "FeatureCollection",
  "features": [
    {
      "assets": {
        "ismz67q9_DELIVERY": {
          "href": "https://api.up42.com/v2/assets/e4a15000-890b-445c-82bb-e4364baac40b",
          "title": "Delivery description",
          "type": "application/pdf",
          "roles": ["metadata"]
        },
        "a80gat4u_VOL_PHR": {
          "href": "https://api.up42.com/v2/assets/e165b992-f32c-4aac-ab7c-e1d289565efa",
          "title": "Delivery metadata",
          "type": "application/xml",
          "role": ["metadata", "bundle"]
        }
      },
      "links": [
        {
          "href": "https://api.up42.com/v2/assets/stac/collections/e165b992-f32c-4aac-ab7c-e1d289565efa/items/9ddc82a8-5304-471e-9e27-a48e6be7e0e0",
          "rel": "self",
          "type": "application/geo+json"
        },
        {
          "href": "https://api.up42.com/v2/assets/stac/collections/e165b992-f32c-4aac-ab7c-e1d289565efa",
          "rel": "parent",
          "type": "application/json"
        },
        {
          "href": "https://api.up42.com/v2/assets/stac/collections/e165b992-f32c-4aac-ab7c-e1d289565efa",
          "rel": "collection",
          "type": "application/json"
        },
        {
          "href": "https://api.up42.com/v2/assets/stac/",
          "rel": "root",
          "type": "application/json"
        }
      ],
      "stac_extensions": [
        "https://stac-extensions.github.io/projection/v1.0.0/schema.json",
        "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
        "https://stac-extensions.github.io/view/v1.0.0/schema.json",
        "https://api.up42.com/stac-extensions/up42-system/v1.0.0/schema.json"
      ],
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [13.386925856393924, 52.529248139608164],
            [13.386943640236675, 52.52876286415917],
            [13.38561749196711, 52.528744780291234],
            [13.385599693519135, 52.529230055424996],
            [13.386925856393924, 52.529248139608164]
          ]
        ]
      },
      "bbox": [13.385599693519135, 52.528744780291234, 13.386943640236675, 52.529248139608164],
      "properties": {
        "gsd": 9.116388106485406,
        "datetime": "2021-05-31T09:51:52.100000+00:00",
        "platform": "SPOT-7",
        "proj:epsg": 32633,
        "end_datetime": "2021-05-31T09:51:52.100000+00:00",
        "view:azimuth": 354.04516708289225,
        "constellation": "SPOT",
        "eo:cloud_cover": 0.0,
        "view:sun_azimuth": 148.72631533959913,
        "view:sun_elevation": 56.46095477929816,
        "up42-system:asset_id": "e4a15000-890b-445c-82bb-e4364baac40b",
        "view:incidence_angle": 11.65164165753593,
        "up42-system:account_id": "8cd5de7b-82e2-4625-b094-d5392f1cf780",
        "up42-system:workspace_id": "7d1cf222-1fa7-468c-a93a-3e3188875997"
      },
      "type": "Feature",
      "stac_version": "1.0.0",
      "id": "9ddc82a8-5304-471e-9e27-a48e6be7e0e0",
      "collection": "e165b992-f32c-4aac-ab7c-e1d289565efa"
    }
  ]
}