STAC Overflow: Map Floodwater from Radar Imagery Hosted By Microsoft AI for Earth


STAC specification

The Planetary Computer catalogs the datasets it hosts using SpatioTemporal Asset Catalog (STAC). STAC is a standardized specification for organizing geospatial assets and metadata, making it easy to search for data that match spatial, temporal, or other criteria.

There are three primary components that together make up the STAC specification.

  • An Item represents a single spatiotemporal asset, or a unit of data and metadata that contains information about the Earth captured at a certain space and time. Examples include GeoJSONs referencing imagery, SAR, data cubes, or full motion videos. Properties of these Items may include spatial extent, temporal extent, band descriptions, label types, or other information like citation examples.

  • A Catalog provides links to Items or to other Catalogs. It can be thought of like a container, similar to a folder in a file structure. In a nested Catalog structure, its root is simply the top-level Catalog without a parent.

  • Finally, a Collection shares most fields with a Catalog, but has a number of additional fields like license, extent, providers, keywords, and summaries. Collections are used like Catalogs to provide structure to files, but generally consist of a set of assets that share higher level metadata (e.g. images from the same sensor).

Planetary Computer STAC API

Microsoft AI provides a STAC API that can be used to search for datasets hosted on the Planetary Computer. A STAC API is the dynamic version of a STAC. It returns a STAC Catalog, Collection, Item or STAC API ItemCollection. Catalog and Collection objects are JSONs, while Item and ItemCollection objects are GeoJSON-compliant entities. These files include spatial and temporal information about the 'child' and 'parent' objects they reference, enabling you to easily traverse the file tree.

Using the PySTAC library created by Azavea, you can load, traverse, and access data within these STACs programmatically. This quickstart guide demonstrates how to search for data using the STAC API with PySTAC. For additional resources on PySTAC, check out the intro to PySTAC blog post, documentation, and tutorials.

To get a SAS Token to enable access to the STAC API, use the Planetary Computer’s Data Authentication API. Alternatively, you can use the planetary-computer package to generate tokens and sign asset HREFs for access.

For this challenge, supplementary data on elevation from the NASA Digital Elevation Model (NASADEM) and global surface water from the European Commission's Joint Research Centre (JRC) are available for use to help your model to better detect floodwater. These datasets can be access through the Collections nasadem and jrc-gsw available from the Planetary Computer STAC API.

The Microsoft AI for Earth team has prepared a great in-depth starter notebook on using the Planetary Computer STAC API with PySTAC. Check out the resources available for this challenge in the Planetary Computer Examples repository to get started.