Detailed STAC item search

Overview

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

Find filter parameters for a detailed STAC item search

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"
    }
  }
}

Parameter	Overview
`$schema`	string The schema of the response.
`$id`	string The URL of the endpoint.
`type`	string The type of resource.
`title`	string The title of the endpoint.
`description`	string The description of the endpoint.
`properties`	object A list of queryable properties to use as search filters.
	Parameters of the `properties` object
`datetime`	object Search by date and time the STAC item was acquired by the provider.
`constellation`	object Search by constellation name.
`gsd`	object Search by ground sample distance.
`cloud_cover`	object Search by cloud coverage.
`workspace_id`	object Search by workspace ID.
`asset_id`	object Search by UP42 asset ID.
`title`	object Search by UP42 asset title.
`tags`	object Search by UP42 asset tags.
`collection_name`	object Search by geospatial collection name.
`order_id`	object 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]
  }
}

Parameter	Overview
`bbox`	array of floats Search for STAC items that intersect this bounding box. Use only if `intersects` isn't specified.
`intersects`	object 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.type`	string / required if Required if `intersects` is spefified. Search by STAC item AOI. The allowed geometry types: `Point` `MultiPoint` `LineString` `MultiLineString` `Polygon` `MultiPolygon`
`collections`	array of strings Search for STAC items in the specified STAC collections.
`datetime`	string 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"`
`filter`	object CQL2 filters. For more information on filters, see the following resources: Common Query Language (CQL2) Filtering and the Common Query Language (CQL)
`filter.args`	array 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.op`	string 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-lang`	string The CQL filter encoding the value used in `filter`. The only supported value is `cql2-json`.
`ids`	array of strings Search for specific STAC items by their IDs.
`limit`	integer The number of STAC items on a results page. The default value is `10`.
`sortby`	array of strings A results sorting method that arranges elements in ascending or descending order based on a chosen field.
`sortby.direction`	string / required if Required if `sortby.field` is specified. An order of sorting. The allowed values: `asc`, `desc`. The default value is ascending.
`sortby.field`	string / required if Required if `sortby.direction` is specified. A field to use for sorting.
`token`	string 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"
    }
  ]
}