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

Response


See response example

JSON

    {
  "$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": {
    "collection": {
      "title": "collection",
      "description": "ID of the parent collection",
      "type": "string"
    },
    "constellation": {
      "title": "constellation",
      "description": "Platform constellation",
      "type": "string"
    },
    "datetime": {
      "title": "datetime",
      "description": "Date and time the feature was captured",
      "type": "timestamp"
    },
    "eo:cloud_cover": {
      "title": "eo:cloud_cover",
      "description": "Cloud coverage",
      "type": "float"
    },
    "geometry": {
      "title": "geometry",
      "description": "Geometry of the STAC item",
      "type": "geometry"
    },
    "gsd": {
      "title": "gsd",
      "description": "Ground Sampling Distance",
      "type": "float"
    },
    "id": {
      "title": "id",
      "description": "ID of the STAC item",
      "type": "string"
    },
    "asset_id": {
      "title": "asset_id",
      "description": "UP42 asset ID",
      "type": "string"
    },
    "collection_name": {
      "title": "collection_name",
      "description": "UP42 collection name",
      "type": "string"
    },
    "data_product_id": {
      "title": "data_product_id",
      "description": "UP42 data product ID",
      "type": "string"
    },
    "job_id": {
      "title": "job_id",
      "description": "UP42 job ID",
      "type": "string"
    },
    "order_id": {
      "title": "order_id",
      "description": "UP42 order ID",
      "type": "string"
    },
    "source": {
      "title": "source",
      "description": "UP42 source of data",
      "type": "string"
    },
    "tags": {
      "title": "tags",
      "description": "UP42 asset tags",
      "type": "array"
    },
    "title": {
      "title": "title",
      "description": "User title",
      "type": "string"
    },
    "workspace_id": {
      "title": "workspace_id",
      "description": "UP42 workspace 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
collectionobject
Search by STAC collection ID.
constellationobject
Search by constellation name.
datetimeobject
Search by date and time the STAC item was acquired by the provider.
eo:cloud_coverobject
Search by cloud coverage.
geometryobject
Search by STAC item geometry.
gsdobject
Search by ground sample distance.
idobject
Search by STAC item ID.
asset_idobject
Search by UP42 asset ID.
collection_nameobject
Search by geospatial collection name.
data_product_idobject
Search by UP42 data product ID.
job_idobject
Search by UP42 job ID.
order_idobject
Search by UP42 order ID.
sourceobject
Search by UP42 data source.
tagsobject
Search by UP42 asset tags.
titleobject
Search by UP42 asset title.
workspace_idobject
Search by UP42 workspace 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


Search by UP42 asset ID and cloud coverage

JSON

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

JSON

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

JSON

    {
  "datetime": "2021-01-12T00:00:00Z/2022-12-18T12:31:12Z",
  "intersects": {
    "type": "Point",
    "coordinates": [32.613, 46.641]
  }
}
  

Search by workspace ID and tags

JSON

    {
  "filter": {
    "op": "and",
    "args": [
      {
        "op": "=",
        "args": [
          {
            "property": "workspace_id"
          },
          "53455ajf-5cfb-4529-1234-c7a012343dd2"
        ]
      },
      {
        "op": "a_contains",
        "args": [
          {
            "property": "tags"
          },
          ["reprocessing"]
        ]
      }
    ]
  }
}
  

ParameterOverview
bboxarray of floats
Search for STAC items that intersect a bounding box in the [min longitude, min latitude, max longitude, max latitude] format. 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

JSON

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