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.
HTTP
GET /v2/assets/stac/queryables HTTP/1.1
Host: api.up42.com
Authorization: Bearer {token}
Shell
curl --location --request GET 'https://api.up42.com/v2/assets/stac/queryables' \
--header 'Authorization: Bearer {token}
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"
}
}
}
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 | |
collection | object Search by STAC collection ID. |
constellation | object Search by constellation name. |
datetime | object Search by date and time the STAC item was acquired by the provider. |
eo:cloud_cover | object Search by cloud coverage. |
geometry | object Search by STAC item geometry. |
gsd | object Search by ground sample distance. |
id | object Search by STAC item ID. |
asset_id | object Search by UP42 asset ID. |
collection_name | object Search by geospatial collection name. |
data_product_id | object Search by UP42 data product ID. |
job_id | object Search by UP42 job ID. |
order_id | object Search by UP42 order ID. |
source | object Search by UP42 data source. |
tags | object Search by UP42 asset tags. |
title | object Search by UP42 asset title. |
workspace_id | object Search by UP42 workspace ID. |
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.
HTTP
POST /v2/assets/stac/search HTTP/1.1
Host: api.up42.com
Content-Type: application/json
Authorization: Bearer {token}
Shell
curl --location --request POST 'https://api.up42.com/v2/assets/stac/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}
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"]
]
}
]
}
}
Parameter | Overview |
---|---|
bbox | array 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. |
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 specified.Search by STAC item AOI. The allowed geometry types:
|
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:
|
filter | object A CQL2 filter. |
filter.args | array of objects Arguments inside of a CQL2 filter. |
filter.op | string Operators inside of a CQL2 filter. |
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. |
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"
}
]
}