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"
},
"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"
}
}
}
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. |
workspace_id | object Search by workspace ID. |
asset_id | object Search by UP42 asset ID. |
tags | object Search by UP42 asset tags. |
eo:cloud_cover | object Search by cloud coverage. |
constellation | object Search by constellation name. |
cloud_cover | object Search by cloud coverage. |
gsd | object Search by ground sample distance. |
title | object Search by UP42 asset title. |
collection_name | object Search by geospatial collection name. |
order_id | object Search by order ID. |
geometry | geometry Search by STAC item geometry. |
id | string Search by STAC item ID. |
collection | string 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]
}
}
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:
|
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. |
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"
}
]
}