STAC

Access STAC objects in storage using the API.


Overview

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.

STAC objects

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.

A diagram of correspondence between API objects

STAC objectDescription
STAC catalogThe starting point for navigating STAC, a top-level object that provides a linking structure for grouping other STAC objects.

API object type: Catalog
STAC collectionA STAC object associated with an order that groups related STAC items and aggregates their summary metadata.

API object type: Collection
STAC itemAn individual scene in a STAC collection that has a unique spatiotemporal extent. Different spatiotemporal extents produce different STAC items.
  • Examples of different spatial extents are tiled images.
  • Examples of different temporal extents are images with different acquisition times.
  • Examples of different spatial and temporal extents are stereo pairs or tri-stereo triples with different angles and acquisition times.
API object type: Feature
STAC assetA 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 extensionA 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:

A schema of UP42 STAC endpoints

STAC catalog

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

  

STAC collections

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"]
    }
  },
  <...>
}

  

STAC items

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:

ParameterOverview
filterobject
A CQL2 filter.
filter.argsarray of objects
Arguments inside of a CQL2 filter.
filter.opstring
Operators inside of a CQL2 filter.

Create a CQL2 filter for the Get specific STAC items endpoint as follows:

  1. Find available parameters by calling the Get queryable filter parameters endpoint.
  2. In filter.args, use a queryable filter parameter in the nested property field and follow it with a value.
  3. 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
    ]
  }
}

  

Arithmetic operators

  • +: addition
  • -: subtraction
  • *: multiplication
  • /: division

Array operators

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

  

Comparison operators

  • =: equal to
  • !=: not equal to
  • <: less than
  • >: greater than
  • <=: less than or equal to
  • >=: greater than or equal to
  • isNull: 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"
    }
  }
}

  

Logical operators

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

  

Spatial operators

  • s_contains
  • s_crosses
  • s_disjoint
  • s_equals
  • s_intersects
  • s_overlaps
  • s_touches
  • s_within

A visual scheme of how s_overlaps and s_intersects work

A visual scheme of how s_contains, s_within, and s_intersects work


A visual scheme of how s_equals and s_intersects work

A visual scheme of how s_crosses and s_intersects work


A visual scheme of how s_disjoint works

A visual scheme of how s_touches works


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

  

Temporal operators

  • 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

Temporal operators

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

  

STAC assets

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.

A diagram showing UP42 assets are mapped on a STAC collection level, and STAC assets are mapped in a STAC item level

STAC assets are returned as part of a STAC item response body. You can get STAC assets in one of the following ways:

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
        }
      ]
    }
  },
  <...>
}

  

Roles

STAC asset roles are used to describe the purpose or function of each asset within a STAC item.

Data roles

RoleDescription
dataA higher-level role for all types of data. The CNAM format transforms all raster assets with the data role into COGs.
multispectralAn asset related to the multispectral band.
panchromaticAn asset related to the panchromatic band.

Metadata roles

RoleDescription
metadataA higher-level role for all types of metadata.
bundleDelivery metadata that contains information about both types of bands, panchromatic and multispectral.
extendedDetailed metadata for multispectral and panchromatic bands.
iso-19115ISO 19115-1:2014 metadata.
licenseAn end-user license agreement (EULA).
lineageProcessing, ground, or strip lineage.
lutA Look-Up-Table with rendering of color curves in a reflectance product.
quality-elevationQuality elevation metadata.
stacSTAC-related metadata.
stereoStereo metadata.
tile-infoTiling metadata.
toa-factorsTop-of-atmosphere reflectance metadata.
angleSensor viewing angle model coefficients.
digestDigest metadata.
auxiliaryAuxiliary metadata.

Preview roles

RoleDescription
overviewA preview image of higher resolution than thumbnail.
thumbnailA low-resolution preview image, usually up to 600×600 px.
visualA full-resolution version of the data, processed for visual use.

Mask roles

RoleDescription
data-maskA higher-level role for all types of masks. The CNAM format transforms all vector assets with the data-mask role into GeoJSON files.
cloudA cloud mask. If an asset has cloud coverage of 5% or lower, cloud masks won’t be provided.
detector-qualityA quality detector mask.
footprintA footprint.
roiA region of interest mask.
saturationA saturation mask.
technical-indexA technical index mask.
visibilityA visibility mask.
water-maskA water detection mask.
cloud-shadowA cloud shadow detection mask.
snow-iceA snow and ice detection mask.

Other roles

RoleDescription
indexSpectral indexes.
rpcRational polynomial coefficients.
temperatureA surface temperature band.
emissivityAn emissivity band.

STAC extensions

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.

UP42 system extension

ParameterOverview
up42-system:sourcestring
The source of data. The allowed values:
  • ARCHIVE
  • TASKING
  • PROCESSING
  • PLATFORM
  • USER
up42-system:account_idstring
The account ID.
up42-system:asset_idstring
The UP42 asset ID.
up42-system:workspace_idstring
The user workspace ID.
up42-system:metadata_versionstring
The metadata version.
up42-system:job_idstring
The ID of the processing job that has generated this STAC object.

UP42 product extension

ParameterOverview
up42-product:
data_type
string
The type of data. The allowed values:
  • raster
  • vector
  • pointcloud
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.

UP42 user extension

ParameterOverview
up42-user:titlestring
A custom title added to the corresponding UP42 asset in storage.
up42-user:tagsstring
Tags added to the corresponding UP42 asset in storage.

UP42 order extension

ParameterOverview
up42-order:idstring
The order ID.
up42-order:statusstring
The status of the order. The allowed value is FULFILLED.
up42-order:host_idstring
The provider order ID.

Earth Search extension

ParameterDescription
earthsearch:boa_offset_appliedboolean
Whether the –0.1 offset added by ESA after January 25, 2022 was applied to the cloud-optimized GeoTIFF.

Sentinel-2 extension

ParameterDescription
s2:sequencestring
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_baselinestring
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.

Learn more