STAC Item Example
Understanding STAC items is central to using the Discovery API to access the Catalog. This section presents an example of a STAC item for a WorldView-3 satellite image.
The file 10400100603CF500.json is a STAC item for image 10400100603CF500 acquired by WorldView-3 satellite on Oct 9, 2020.
STAC Item
The building block for the STAC Catalog is the "Item". It is a geolocated JSON object that contains metadata and STAC Assets which are provider-owned data objects. The object itself is a GeoJSON Feature which has the following keys:
Example: Worldview-1 Satellite Image
This image has important metadata such as when it was collected, satellite orientation, gsd, and more.
| Item | Description |
|---|---|
| id | Unique identifier for the item in the entire Discovery Catalog. |
| bbox | Bounding box of the asset. |
| geometry | GeoJSON location of the item. |
| properties | Key-value pairs of searchable metadata. |
| assets | Key-Asset Object pairs that provide urls to get to the assets. |
STAC Collection
STAC Collections are designed to act like a folder to group a set of Items that share properties and metadata to allow users to easily browse related assets and search across them both spatially and temporally.
| Item | Description |
|---|---|
| id | Identifier for the collection that is unique across the entire Discovery Catalog. |
| title | One-line descriptor for the collection. |
| description | Multi-line description to fully explain the collection. |
| providers | list of providers who either license, host, producer, or process the items in this collection. |
| extent | Spatial and temporal extents of the items held in the collection. |
| summaries | Key-json pairs to give insight on the metadata's description and expected values in all of its items. |
| links | Context and info for the collection. |
| assets | Collection specific assets that can be downloaded or streamed. |
Collections
Items in the Discovery Catalog are organized into collections. Every item belongs to one collection.
The following table shows the collections used for Maxar satellite imagery. Multiple collections are used for WorldView-3 images because that satellite has multiple sensors.
| Collection name | Description |
|---|---|
| ge01 | GeoEye-1 images |
| wv01 | WorldView-1 images |
| wv02 | WorldView-2 images |
| wv03-vnir | WorldView-3 VNIR images |
| wv03-swir | WorldView-3 SWIR images |
| wv04 | WorldView-4 images |
| lg01 | WorldView Legion-1 images |
| lg02 | WorldView Legion-2 images |
| lg03 | WorldView Legion-3 images |
| lg04 | WorldView Legion-4 images |
The catalog has some other collections for resources besides individual satellite images. For example these collections contain pairs of in-track stereo imagery:
| Collection name |
|---|
| ge01-intrack-stereo |
| wv01-intrack-stereo |
| wv02-intrack-stereo |
| wv03-swir-intrack-stereo |
| wv03-vnir-intrack-stereo |
And there are a variety of other collections:
| Collection name | Description |
|---|---|
| dg-dem | Digital elevation models (DEM) |
| mosaics | VIVID mosaics |
| multi-sensor-image-pair | Stereo pairs between images from different sensors |
In the above tables the collection name is the value to use in URL's in the REST API. Collection names are case-sensitive.
Collections can optionally be part of a hierarchy. For example the various collections for WorldView and GeoEye images all belong to the "parent" collection dg-archive. Parent collections like dg-archive do not themselves contain any STAC items, instead they act as containers for other collections.
STAC item identifiers
Every STAC item always has an id property. This is some kind of identifier that uniquely identifies every item in the database.
The STAC specification intends that all data providers generate id values that are globally unique. See the Stac Item Spec. In the case of Maxar satellite images this is the case. All image IDs for items in the standard imagery collections (ge01, wv01, wv02, wv03-vnir, wv03-swir, wv04) will be unique across all Maxar satellites.
However, the Discovery Catalog does have items with duplicate id values in its mosaic collections, since items in mosaic collection use quadkeys as identifiers. So when querying items in mosaic collections you have to be prepared to deal with duplicate id values, depending on the collections you are querying. All items inside a single collection will have unique id values.