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"
    },
    "constellation": {
      "title": "constellation",
      "description": "Platform constellation",
      "type": "string"
    },
    "gsd": {
      "title": "gsd",
      "description": "Ground Sampling Distance",
      "type": "float"
    },
    "cloud_cover": {
      "title": "cloud_cover",
      "description": "Cloud Coverage",
      "type": "float"
    },
    "workspace_id": {
      "title": "workspace_id",
      "description": "UP42 Workspace Id",
      "type": "string"
    },
    "asset_id": {
      "title": "asset_id",
      "description": "UP42 Asset Id",
      "type": "string"
    },
    "title": {
      "title": "title",
      "description": "User Title",
      "type": "string"
    },
    "tags": {
      "title": "tags",
      "description": "UP42 Asset Tags",
      "type": "array"
    },
    "collection_name": {
      "title": "collection_name",
      "description": "UP42 Collection Name",
      "type": "string"
    },
    "order_id": {
      "title": "order_id",
      "description": "UP42 Order Id",
      "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.
constellationobject
Search by constellation name.
gsdobject
Search by ground sample distance.
cloud_coverobject
Search by cloud coverage.
workspace_idobject
Search by workspace ID.
asset_idobject
Search by UP42 asset ID.
titleobject
Search by UP42 asset title.
tagsobject
Search by UP42 asset tags.
collection_nameobject
Search by geospatial collection name.
order_idobject
Search by order 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
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": "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
CQL2 filters. For more information on filters, see the following resources:
filter.argsarray of objects
CQL2 arguments. Use with the filter.op parameter.

Use queryable properties in the nested property field and follow it with the value. An example of usage: "args": [{"property": "cloud_cover"},"20.0"]
filter.opstring
CQL2 operators. Use with the filter.args parameter.

The allowed values:
  • Logical operators: and, or, not.
  • Comparison operators: =, <, >, <=, >=, is null, like, between, in.
  • Array operators: a_contains, a_overlap.
  • Spatial operators: s_intersects, s_overlaps, s_crosses, s_within, s_disjoint, s_touches.
  • Temporal operators: t_after, t_before, t_during, t_overlaps, t_overlappedby, t_meets, t_metby.
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": {
        "data": {
          "href": "https://api.up42.com/v2/assets/e4a15000-890b-445c-82bb-e4364baac40b"
        }
      },
      "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"
    }
  ]
}