STAC

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 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. 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 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:

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. It’s an UP42 asset you receive after a completed order or a finished processing job.

A STAC collection contains different storage characteristics — for example, a geospatial collection name, a provider 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 update the title or tags of a STAC item, call the Update a STAC item endpoint with the STAC collection ID and the STAC item ID as path parameters, and the new values in the request body, for example:

JSON

    {
  "up42-user:title": "SPOT 6/7 NY Central Park",
  "up42-user:tags:": ["optical", "berlin"]
}

Simple search

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.

Detailed search

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

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:

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

Roles

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

Data roles

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.

Metadata roles

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.

Preview roles

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.

Mask roles

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.

Other roles

Role	Description
`index`	Spectral indexes.
`rpc`	Rational polynomial coefficients.
`temperature`	A surface temperature band.
`emissivity`	An 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

Parameter	Overview
`up42-system:source`	string The source of data. The allowed values: `ARCHIVE` `TASKING` `PROCESSING` `PLATFORM` `USER`
`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.

UP42 product extension

Parameter	Overview
`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

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.

UP42 order extension

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.

Earth Search extension

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.

Sentinel-2 extension

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.

Access STAC objects in storage using the API.

Overview

STAC objects

STAC catalog

STAC collections

STAC items

Simple search

Detailed search

Arithmetic operators

Array operators

Comparison operators

Logical operators

Spatial operators

Temporal operators

STAC assets

Roles

Data roles

Metadata roles

Preview roles

Mask roles

Other roles

STAC extensions

UP42 system extension

UP42 product extension

UP42 user extension

UP42 order extension

Earth Search extension

Sentinel-2 extension

Learn more