SpatioTemporal Asset Catalogs (STAC)

STAC provides a common standard for organising and displaying geospatial information that is simple and lightweight. Any asset that captures information of the Earth in both time and geospatial extents can be considered a spatio-temporal asset.

This page describes each of the entities within the STAC specification that are relevant to using DataCosmos.

Catalog

A Catalog is a top-level object that logically groups together other Catalogs, Collections and Items. It contains an array of Link objects, each of which links to another resource, typically another Catalog or Collection.

• id - Unique identifier used when querying for Items in this Collection.
• title - Title of the Collection: e.g. “Mantis L1D Data Products”.
• description - A human readable description of the Collection.
• links - List of objects containing URLs to other related STAC objects.
  • href - A URL link to the corresponding object.
  • rel - Relationship between the current and linked documents can be either self, root, parent, child or Item.
  • type - Specifies the content-type of the linked object.
  • title - Human readable title that can be rendered in displays of the link.

Collection

The STAC Collection specification defines a set of common fields to describe a group of Items that share properties and metadata, and is represented in a JSON format. More information on the required and optional fields of the Collection can be found in the STAC specification.

DataCosmos Collections use the following fields with corresponding descriptions of their purpose.

• id - Unique identifier used when querying for Items in this Collection.
• title - Title of the Collection: e.g. “Mantis L1D Data Products”.
• description - A human readable description of the Collection.
• license - A string that identifies the applicable license for the Collection and data contained within it. This will contain the DataCosmos EULA.
• providers - A list of providers that includes the organisations responsible for capturing, processing and hosting the data in a chronological order.
• extent
  • spatial - The spatial range in latitude and longitude that the Collection covers. This value is updated over time as new Items are assigned to the Collection.
  • temporal - The temporal range specifying the time window the Collection covers. This value is updated over time as new Items are assigned to the Collection.
• summaries - A mapping of key:value summaries where the value can be either a string, range or JSON object.
  • platform - List of strings specifying the satellite platform the data product is captured from.
  • instrument - List of strings specifying the payload instruments used to capture the data products.
  • gsd - The minimum and maximum GSD of the data products.
  • eo:bands - Defined as part of the EO extension
    • name - Name of the corresponding band in the Collection's Items.
    • common_name - Name commonly used to refer to the band from an accepted list of names to allow for searching across instruments.
    • description - Description of the corresponding band.
    • center_wavelength - The center wavelength of the band in micrometers.
• links - List of objects containing URLs to other related STAC objects.
• item_assets - List of asset objects that match the assets contained within each Item of the Collection. This is used to predetermine the keys of the assets before searching the Collection. Defined as part of the Item Assets extension.

Item

A STAC Item is an augmented GeoJSON Feature object that contains additional fields as part of the STAC specification. These additional fields provide more information on the data contained within the Item and can be used for filtering during searches. The STAC Item inherits the id, type, bbox, geometry and properties fields from the GeoJSON standard. More information on the specification and fields used in the Item definition can be found in the STAC Item specification

• id - Unique ID corresponding to the Item.
• geometry - GeoJSON object that describes the footprint of the Item. Coordinates specified in longitude and latitude. This geometry object is used when searching for data products within a specified geographical region. Formatted according to RFC 7946.
• bounding box - Bounding box of the Item, formatted according to RFC 7946.
• collection - ID of the Collection the Item belongs to.
• properties - Dictionary of additional metadata
  • datetime - The acquisition time of the image. Field used when searching for data products within a specified time range.
  • created - Timestamp for when the data product was created in the database.
  • updated - Timestamp for when the data product was created in the database.
  • platform - String specifying the satellite platform the data product is captured from.
  • instruments - List of strings specifying the payload instruments used to capture the data products.
  • gsd - The GSD of the data product.
  • view:off_nadir - Angle between nadir and the pointing of the sensor.
  • view:incidence_angle - Angle between the normal to the intercepting surfaces and line of sight to the sensor from the scene center.
  • view:azimuth - Angle measured from the sub-satellite point between the scene center and true north.
  • view:sun_azimuth - Angle from true north at the scene center to the center point of the sun.
  • view:sun_elevation - Angle from the tangent of the scene center point to the sun.
  • eo:cloud_cover - The percentage of cloud coverage in the data products. Added as part of the STAC EO extension.
  • opencosmos:price - The price of the data product for the authenticated user. This value is dynamically computed on each request and reflects the terms of the user's contract. See the important note on pricing below.
  • opencosmos:price_currency - The currency of the price (e.g. GBP, USD).
  • opencosmos:high_resolution_read_permission - A boolean indicating whether the authenticated user has access to the high-resolution assets of this item.
  • opencosmos:data_area_km2 - The area of the data product footprint in square kilometres.
• assets - Contain a list of objects that describe each of the associated assets with the data product such as the image data and metadata files.
  • title - Title of the asset.
  • description - Human readable description of what the asset contains.
  • href - Contains a URL to the asset location.
  • type - Contains the content-type of the asset to enable end user applications to automatically read the source data.
  • roles - Defined by the STAC specification, roles are used to describe the purpose of each asset. More information can be found in the Item specification.
• links - List of objects containing URLs to other related STAC objects.

Extensions

There are several extensions which have been proposed and added to the STAC specification. In order to make the DataCosmos STAC database easier to navigate and richer with information we have adopted the following extensions as standard.

• View Geometry - Adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data.
• Electro-Optical - Adds metadata relating to the EO data bands and cloud coverage.
• Item Assets - Adds common Item assets to the Collection to provide a human readable and programmatic way of determining assets available in the Collection's Items.
• Query - Enables property-based filtering of Items during searches using comparison operators such as eq, neq, lt, lte, gt, gte, startsWith, endsWith, contains, and in.

A Note on Pricing

When retrieving Items from the catalog (whether through the search endpoint, listing items in a collection, or fetching a single item) each Item includes pricing information in its properties (opencosmos:price and opencosmos:price_currency).

There are a few important things to be aware of:

• Prices are calculated dynamically on every request. They are not stored as part of the Item metadata. Each time you request an Item, the price is freshly computed based on your account's contract terms.
• Prices are personalised. The price returned is specific to the authenticated user making the request. Different users may see different prices for the same Item depending on their contract.
• Do not store or cache prices. Because prices depend on your contract terms and may change over time, you should always retrieve a fresh price from the API before presenting it to end users or using it in purchasing decisions. Any previously retrieved price should be treated as indicative only.
• The currency is included alongside the price. Always use the opencosmos:price_currency field to determine the currency of the quoted price rather than assuming a default.

Where to Next