SpatioTemporal Asset Catalog (STAC) is a specification designed to establish a standard in geospatial data. It allows searching across multiple providers for geospatial assets which share a common structure and set of metadata.
UP42 has two sets of asset APIs:
/v2/assets
allows you to manage and download UP42 assets in your storage./v2/assets/stac
allows you to retrieve STAC objects related to your UP42 assets.
STAC object | Description |
---|---|
STAC catalog | The starting point for navigating STAC, a top-level object that provides a linking structure for grouping other STAC objects. API object type: Catalog |
STAC collection | A STAC object associated with an order that groups related STAC items and aggregates their summary metadata. API object type: Collection |
STAC item | An individual scene in a STAC collection that has a unique spatiotemporal extent. Different spatiotemporal extents produce different STAC items.
Feature |
STAC asset | A geospatial feature of a STAC item, its mask, preview, or metadata file. For example, an image captured by an optical satellite would produce a STAC asset for the combination of its multispectral bands, and a separate STAC asset for its panchromatic data. API object type: assets in Feature |
STAC extension | A JSON schema with additional parameters available for a specific STAC object. Extensions differ based on data availability, sensor, and constellation. |
The structure of the API represents how different STAC objects are nested within each other:
To get information about the version of the API and its extensions, call the Get a STAC catalog endpoint.
You’ll get a list of links outlining the specifications the API adheres to, in the conformsTo
parameter:
JSON
{
"conformsTo": [
"https://api.stacspec.org/v1.0.0-rc.1/item-search#context",
"http://www.opengis.net/spec/cql2/1.0/conf/cql2-text",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
"https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features",
<...>
],
"links": [ <...> ],
"stac_extensions": [],
"title": "UP42 Storage",
"description": "UP42 Storage STAC API",
"stac_version": "1.0.0",
"id": "up42-storage",
"type": "Catalog"
}
A STAC collection is an object associated with an order delivery. A STAC collection contains different storage characteristics — for example, a geospatial collection name, a producer name, and a corresponding UP42 asset ID. An order can produce multiple STAC collections.
- To get a list of all STAC collections in your storage, call the Get STAC collections endpoint.
- To get a specific STAC collection, call the Get a STAC collection endpoint with the STAC collection ID as the path parameter.
A STAC collection object contains an assets
object, but it’s not a transformed STAC asset. It’s the original delivery that hasn’t been CNAM-transformed:
JSON
{
"assets": {
"68567134-27ad-7bd7-4b65-d61adb11fc78": {
"href": "https://api.up42.com/v2/assets/68567134-27ad-7bd7-4b65-d61adb11fc78",
"title": "Original Delivery",
"description": null,
"type": "application/zip",
"roles": ["data", "original"]
}
},
<...>
}
A STAC item is an individual scene that represents inseparable data and metadata. A STAC item has a unique spatiotemporal extent, that is, has one AOI and acquisition time in its characteristics. For example, an order with a stereo acquisition mode will produce a STAC collection with two STAC items — one for each image of a slightly different AOI and acquisition time. Every STAC item is attributed to a STAC collection.
-
To get a list of all STAC items from a STAC collection, call the Get STAC items endpoint with the STAC collection ID as the path parameter.
-
To get information about a specific STAC item, call the Get a STAC item endpoint with the STAC collection ID and the STAC item ID as path parameters.
To search for STAC items with specific parameters across your storage, call the Get specific STAC items endpoint with your search parameters in the request body.
Common Query Language (CQL2) is a filter grammar that can be used to search for STAC items. A CQL2 filter consists of rules, while rules consist of arguments and operators. An argument is a value of a specific property you can choose from the available filter parameters.
The structure of a request body for a detailed search:
Parameter | Overview |
---|---|
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. |
Create a CQL2 filter for the Get specific STAC items endpoint as follows:
- Find available parameters by calling the Get queryable filter parameters endpoint.
- In
filter.args
, use a queryable filter parameter in the nestedproperty
field and follow it with a value. - In
filter.op
, add an operator.
An example of a filter that searches for STAC items with cloud coverage less than 20%:
JSON
{
"filter": {
"op": "<",
"args": [
{
"property": "eo:cloud_cover"
},
20.0
]
}
}
+
: addition-
: subtraction*
: multiplication/
: division
a_contains
: search for STAC items that contain all array values in their parameters.a_overlaps
: search for STAC items that contain at least one array value in their parameters.
An example with a_contains
that returns STAC items with both optical
and aerial
in their tags
JSON
{
"filter": {
"op": "a_contains",
"args": [
{
"property": "tags"
},
["optical", "aerial"]
]
}
}
An example with a_overlaps
that returns STAC items with either optical
or aerial
in their tags
JSON
{
"filter": {
"op": "a_overlaps",
"args": [
{
"property": "tags"
},
["optical", "aerial"]
]
}
}
=
: equal to!=
: not equal to<
: less than>
: greater than<=
: less than or equal to>=
: greater than or equal toisNull
: the value is null
An example with =
that returns STAC items associated with a specific asset ID
JSON
{
"filter": {
"op": "=",
"args": [
{
"property": "asset_id"
},
"b9fc2b75-f9de-46dd-a21b-320381bbb62d"
]
}
}
An example with !=
that returns STAC items with data product IDs that don’t match the specified one
JSON
{
"filter": {
"op": "!=",
"args": [
{
"property": "data_product_id"
},
"b0e4a80e-6a54-486c-ac0c-44497b602545"
]
}
}
An example with <
that returns STAC items created on or before June 27, 2023
JSON
{
"filter": {
"op": "<",
"args": [
{
"property": "created"
},
"2023-06-27T00:00:00.000Z"
]
}
}
An example with >
that returns STAC items with cloud coverage greater than 20%
JSON
{
"filter": {
"op": ">",
"args": [
{
"property": "eo:cloud_cover"
},
20.0
]
}
}
An example with <=
that returns STAC items with a datetime on or before June 27, 2024
JSON
{
"filter": {
"op": "<=",
"args": [
{
"property": "datetime"
},
"2022-06-27T00:00:00.000Z"
]
}
}
An example with >=
that returns STAC items with a ground sampling distance greater than 57 cm
JSON
{
"filter": {
"op": ">=",
"args": [
{
"property": "gsd"
},
0.57
]
}
}
An example with isNull
that returns STAC items with no tags
JSON
{
"filter": {
"op": "isNull",
"args": {
"property": "tags"
}
}
}
and
: search for STAC items whose parameter values satisfy both arguments.or
: search for STAC items whose parameter values satisfy any of the arguments.not
: exclude STAC items whose parameter values satisfy the argument.
An example with and
that returns STAC items that have a ground sampling distance less than or equal to 70 cm, and cloud coverage less than or equal to 20%
JSON
{
"filter": {
"op": "and",
"args": [
{
"op": "<=",
"args": [
{
"property": "gsd"
},
0.7
]
},
{
"op": "<=",
"args": [
{
"property": "eo:cloud_cover"
},
20.0
]
}
]
}
}
An example with or
that returns STAC items that either have "constellation": "PNEO"
or "collection_name": "pneo-tasking"
in their parameters.
JSON
{
"filter": {
"op": "or",
"args": [
{
"op": "=",
"args": [
{
"property": "constellation"
},
"PNEO"
]
},
{
"op": "=",
"args": [
{
"property": "collection_name"
},
"pneo-tasking"
]
}
]
}
}
An example with not
that returns STAC items that don’t have "constellation": "PNEO"
in their parameters
JSON
{
"filter": {
"op": "not",
"args": [
{
"op": "=",
"args": [
{
"property": "constellation"
},
"PNEO"
]
}
]
}
}
s_contains
s_crosses
s_disjoint
s_equals
s_intersects
s_overlaps
s_touches
s_within
An example with s_contains
that returns STAC items whose AOIs contain the defined polygon
JSON
{
"filter": {
"op": "s_contains",
"args": [
{
"property": "geometry"
},
{
"type": "Polygon",
"coordinates": [
[
[13.313668486610595, 52.55356060142003],
[13.313668486610595, 52.45865541990574],
[13.480777670201348, 52.45865541990574],
[13.480777670201348, 52.55356060142003],
[13.313668486610595, 52.55356060142003]
]
]
}
]
}
}
An example with s_crosses
that returns STAC items whose AOIs cross the defined line
JSON
{
"filter": {
"op": "s_crosses",
"args": [
{
"property": "geometry"
},
{
"type": "LineString",
"coordinates": [
[13.341955808701016, 52.51969146420771],
[13.366237996993789, 52.504786810390584]
]
}
]
}
}
An example with s_disjoint
that returns STAC items that don’t intersect with the defined polygon
JSON
{
"filter": {
"op": "s_disjoint",
"args": [
{
"property": "geometry"
},
{
"type": "Polygon",
"coordinates": [
[
[13.313668486610595, 52.55356060142003],
[13.313668486610595, 52.45865541990574],
[13.480777670201348, 52.45865541990574],
[13.480777670201348, 52.55356060142003],
[13.313668486610595, 52.55356060142003]
]
]
}
]
}
}
An example with s_equals
that returns STAC items whose AOIs exactly match the defined polygon
JSON
{
"filter": {
"op": "s_equals",
"args": [
{
"property": "geometry"
},
{
"type": "Polygon",
"coordinates": [
[
[13.370867464340053, 52.48392869357015],
[13.356655389450955, 52.49894514421745],
[13.356759290471304, 52.49912191483249],
[13.363463410709915, 52.505445701439136],
[13.40398287087849, 52.505257472987886],
[13.370867464340053, 52.48392869357015]
]
]
}
]
}
}
An example with s_within
that returns STAC items whose AOIs are within the defined polygon
JSON
{
"filter": {
"op": "s_within",
"args": [
{
"property": "geometry"
},
{
"type": "Polygon",
"coordinates": [
[
[-123.47593244349214, 48.65881246874093],
[-123.44562410769204, 48.65893370548264],
[-123.44429739341179, 48.658161559812235],
[-123.44376648785145, 48.65522725021609],
[-123.47599504628167, 48.655076990420135],
[-123.47602614621897, 48.65838026437638],
[-123.47601340902926, 48.658758157043785],
[-123.47593244349214, 48.65881246874093],
[-123.47593244349214, 48.65881246874093]
]
]
}
]
}
}
An example with s_intersects
that returns STAC items whose AOIs intersect with the defined polygon
JSON
{
"filter": {
"op": "s_intersects",
"args": [
{
"property": "geometry"
},
{
"type": "Polygon",
"coordinates": [
[
[13.370867464340053, 52.48392869357015],
[13.356655389450955, 52.49894514421745],
[13.356759290471304, 52.49912191483249],
[13.363463410709915, 52.505445701439136],
[13.40398287087849, 52.505257472987886],
[13.370867464340053, 52.48392869357015]
]
]
}
]
}
}
An example with s_overlaps
that returns STAC items whose AOIs overlap with the defined polygon
JSON
{
"filter": {
"op": "s_overlaps",
"args": [
{
"property": "geometry"
},
{
"type": "Polygon",
"coordinates": [
[
[13.370867464340053, 52.48392869357015],
[13.356655389450955, 52.49894514421745],
[13.356759290471304, 52.49912191483249],
[13.363463410709915, 52.505445701439136],
[13.40398287087849, 52.505257472987886],
[13.370867464340053, 52.48392869357015]
]
]
}
]
}
}
An example with s_touches
that returns STAC items whose AOIs touch the defined point
JSON
{
"filter": {
"op": "s_touches",
"args": [
{
"property": "geometry"
},
{
"type": "Point",
"coordinates": [-123.47593244349214, 48.65881246874093]
}
]
}
}
t_after
t_before
t_contains
t_during
t_equals
t_finishes
t_finishedby
t_meets
t_metby
t_overlaps
t_overlappedby
t_starts
t_startedby
Use date and time in the ISO 8601 format: YYYY‐MM‐DDThh:mm:ssZ
Depending on the operator, you must pass an argument as a datetime string ("2023-03-21T00:00:00.000Z"
) or as an interval:
JSON
{
"interval": ["2021-03-21T00:00:00.000Z", "2023-04-18T00:00:00.000Z"]
}
An example with t_after
that returns STAC items acquired after March 21, 2023
JSON
{
"filter": {
"op": "t_after",
"args": [
{
"property": "datetime"
},
"2023-03-21T00:00:00.000Z"
]
}
}
An example with t_before
that returns STAC items acquired before March 21, 2023
JSON
{
"filter": {
"op": "t_before",
"args": [
{
"property": "datetime"
},
"2023-03-21T00:00:00.000Z"
]
}
}
An example with t_equals
that returns STAC items acquired on March 21, 2023
JSON
{
"filter": {
"op": "t_equals",
"args": [
{
"property": "datetime"
},
"2021-03-21T00:00:00.000Z"
]
}
}
An example with t_overlaps
that returns STAC items acquired between March 21, 2023, and April 18, 2023
JSON
{
"filter": {
"op": "t_overlaps",
"args": [
{
"property": "datetime"
},
{
"interval": ["2023-03-21T00:00:00.000Z", "2023-04-18T00:00:00.000Z"]
}
]
}
}
A STAC asset is a geospatial feature of a STAC item. For example, a band in an optical image, a thumbnail, or a metadata file. The CNAM format transforms an UP42 asset from an order into individual geospatial features available for immediate download. Regardless of provider or delivery format, all order assets that fall within the criteria are transformed into a standard model.
The contents of the assets
parameter are different, depending on the type of object:
- Inside a STAC item object, CNAM-transformed elements are presented as individual STAC assets.
- Inside a STAC collection object, the order’s original delivery is the only asset. This isn’t a transformed STAC asset.
STAC assets are returned as part of a STAC item response body. You can get STAC assets in one of the following ways:
- By requesting a list of all STAC items from a specific STAC collection.
- By requesting a specific STAC item.
- By making a detailed STAC item search request.
An example of a STAC asset:
JSON
{
<...>,
"assets": {
"mgag5ui3_img_phr1a_ms_202208080011285_sen_6452562101-2.tiff": {
"href": "https://api.up42.com/v2/assets/e4a15000-890b-445c-82bb-e4364baac40b",
"title": "Multispectral data",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": ["data", "multispectral"],
"gsd": 0.7283,
"eo:bands": [
{
"name": "blue", // The name of the band.
"common_name": "blue", // The name commonly used to refer to the band to make it easier to search for bands.
"center_wavelength": 0.47, // The center wavelength of the band, in micrometers.
"full_width_half_max": 0.07 // The width of the band, as measured at half the maximum transmission, in micrometers.
},
{
"name": "green",
"common_name": "green",
"center_wavelength": 0.47,
"full_width_half_max": 0.07
},
{
"name": "red",
"common_name": "red",
"center_wavelength": 0.665,
"full_width_half_max": 0.038
}
]
}
},
<...>
}
STAC asset roles are used to describe the purpose or function of each asset within a STAC item.
Role | Description |
---|---|
data | A higher-level role for all types of data. The CNAM format transforms all raster assets with the data role into COGs. |
multispectral | An asset related to the multispectral band. |
panchromatic | An asset related to the panchromatic band. |
Role | Description |
---|---|
metadata | A higher-level role for all types of metadata. |
bundle | Delivery metadata that contains information about both types of bands, panchromatic and multispectral. |
extended | Detailed metadata for multispectral and panchromatic bands. |
iso-19115 | ISO 19115-1:2014 metadata. |
license | An end-user license agreement (EULA). |
lineage | Processing, ground, or strip lineage. |
lut | A Look-Up-Table with rendering of color curves in a reflectance product. |
quality-elevation | Quality elevation metadata. |
stac | STAC-related metadata. |
stereo | Stereo metadata. |
tile-info | Tiling metadata. |
toa-factors | Top-of-atmosphere reflectance metadata. |
angle | Sensor viewing angle model coefficients. |
digest | Digest metadata. |
auxiliary | Auxiliary metadata. |
Role | Description |
---|---|
overview | A preview image of higher resolution than thumbnail . |
thumbnail | A low-resolution preview image, usually up to 600×600 px. |
visual | A full-resolution version of the data, processed for visual use. |
Role | Description |
---|---|
data-mask | A higher-level role for all types of masks. The CNAM format transforms all vector assets with the data-mask role into GeoJSON files. |
cloud | A cloud mask. If an asset has cloud coverage of 5% or lower, cloud masks won’t be provided. |
detector-quality | A quality detector mask. |
footprint | A footprint. |
roi | A region of interest mask. |
saturation | A saturation mask. |
technical-index | A technical index mask. |
visibility | A visibility mask. |
water-mask | A water detection mask. |
cloud-shadow | A cloud shadow detection mask. |
snow-ice | A snow and ice detection mask. |
Role | Description |
---|---|
index | Spectral indexes. |
rpc | Rational polynomial coefficients. |
temperature | A surface temperature band. |
emissivity | An emissivity band. |
STAC is extensible, being a network of JSON files that follow corresponding specifications. A STAC extension is a JSON schema with additional parameters available for a specific STAC collection or a STAC item.
STAC extensions contain descriptions of parameters with {prefixes}:
. UP42 has platform-specific extensions.
Parameter | Overview |
---|---|
up42-system:source | string The source of data. The allowed values:
|
up42-system:account_id | string The account ID. |
up42-system:asset_id | string The UP42 asset ID. |
up42-system:workspace_id | string The user workspace ID. |
up42-system:metadata_version | string The metadata version. |
up42-system:job_id | string The ID of the processing job that has generated this STAC object. |
Parameter | Overview |
---|---|
up42-product: data_type | string The type of data. The allowed values:
|
up42-product: modality | string The modality of data that depends on the data type. For example, multispectral or hyperspectral. |
up42-product: collection_name | string The geospatial collection name. |
up42-product: product_id | string The product ID. |
Parameter | Overview |
---|---|
up42-user:title | string A custom title added to the corresponding UP42 asset in storage. |
up42-user:tags | string Tags added to the corresponding UP42 asset in storage. |
Parameter | Overview |
---|---|
up42-order:id | string The order ID. |
up42-order:status | string The status of the order. The allowed value is FULFILLED . |
up42-order:host_id | string The provider order ID. |
Parameter | Description |
---|---|
earthsearch:boa_offset_applied | boolean Whether the –0.1 offset added by ESA after January 25, 2022 was applied to the cloud-optimized GeoTIFF. |
Parameter | Description |
---|---|
s2:sequence | string The version number of the data. Values other than 0 mean that this is either a processed version of the STAC item or another image taken for that tile on a given date. |
s2:processing_baseline | string The version of the Ground Image Processing Parameters used by ESA to process the raw Sentinel-2 data into level 1C and level 2A products. |