Skip to content

STAC Item Metadata

Last updated: December 1, 2022


Overview

ARD order deliveries include a STAC Item Metadata file describing the tile and its assets, in JSON format. The item schema adheres to the version of the STAC item specification referred to in the document. STAC and custom extensions are used to extend the metadata.

Extensions

Extensions allow the STAC specification to describe data in more specific terms. Maxar ARD uses extensions designed for describing satellite imagery and adds a custom "tile" extension for describing fields specific to the data within the grid tile bounds.

Extension Type Field name prefix Description
electro-optical STAC eo Data that represents a snapshot of the Earth for a single date and time. It could consist of multiple spectral bands in any part of the electromagnetic spectrum.
Projection STAC proj Describes items whose assets are in a geospatial projection.
View Geometry STAC view Adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data.
Raster STAC raster Describes raster assets at band level (one or multiple).
Grid STAC grid Provides fields related to gridded data products.
Classification STAC classification Used when one or more unique coded integer values are present within a raster asset or band therein. These coded values translate to classes of data with verbose descriptions.
tile custom tile Data specific to imagery tiles.

Item fields

This table describes the primary metadata for a tile. Additional metadata fields for objects are listed in separate tables.

Field Type Description Example
type string The type of the GeoJSON object. The type for a STAC item is "feature". "type": "Feature"
stac_version string The STAC version used by the item. "stac_version": "1.0.0"
stac_extensions string Extensions implemented with the STAC item. ARD implements the projection, geometry, and electro-optical(eo) extensions. "stac_extensions": ["https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/eo/v1.0.0/schema.json"]
id string The unique identifier for an item. The ID for the ARD item is utm_zone/quadkey/acquisitionID. "id": "11/031311311232/104001006D0BB300"
bbox number The bounding box coordinates for the item, projected to wgs84. "bbox": [-117.29404086049149, 32.89643160060904, -117.26563783226379, 32.94040782110711]
geometry GeoJSON geometry object The geometry coordinates for the polygon, projected to wgs84. "geometry":
properties object Additional metadata for the item. See Properties table below.
links object A list of links to resources and additional URLs. See Links table below.
assets object A list of assets and their metadata. Assets are downloadable objects for the item. See Assets table below.
collection string The unique identifier for the STAC collection referenced in this item. The unique identifier is the AcquisitionID. "collection": "104001006D0BB300"

Properties object

The properties object lists additional metadata for the item. When a property is prepended by a {name}:, this indicates the STAC extension the property is derived from.

Field Type Description Example
datetime string An ISO-8601-formatted string to indicate the imagery date. To indicate a range use a / to separate two date strings, e.g. ā€œ2019-10-25T09:00:00Z/2020-10-26T13:00:00Zā€; for open-ended ranges use .. as the date e.g. "2019-10-25T09:00:00Z/.. "datetime": "2021-09-21 18:34:57Z"
platform string The satellite that acquired the image. "platform": "WV03"
gsd number The spatial resolution, or ground sampling distance, of the sensor that acquired the image, stated in meters. "gsd": 0.32
ard_metadata_version string The version number assigned to ARD metadata. "ard_metadata_version": "0.0.1"
catalog_id string The unique identifier for the item, as assigned by the provider, Maxar. This is also referred to as the "acquisition ID". "catalog_id": "104001006D0BB300"0
utm_zone number The Universal Transverse Mercator(UTM) coordinate system number assigned to the zone where the item is located. "utm_zone": 11
proj:epsg integer The coordinate reference system used by the asset data. Maxar ARD uses "epsg". "proj:epsg": 32611
proj: geometry GeoJSON geometry object Defines the footprint of this Item in native UTM projection. see example below this table.
proj:bbox number Bounding box of the Item in the asset coordinate reference system (CRS), in 2 or 3 dimensions; native UTM projection. see example below this table.
quadkey string The address where the item is located on the Maxar grid. "quadkey": "031311311232"
tile:data_area number The square kilometer area of the tile with data. "tile:data_area": 12.8
tile:clouds_area number The square kilometer area of the tile that has clouds. "tile:clouds_area": 0
tile:clouds_percent number The percentage of the tile that is covered by clouds. "tile:clouds_percent": 0
view:off_nadir number The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). "view:off_nadir": 13.0
view:azimuth number Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). "view:azimuth": 153.5
view:incidence_angle number The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90). "view:incidence_angle": 74.7
view:sun_azimuth number Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360). "view:sun_azimuth": 150.7
view:sun_elevation number Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (-90-90). Maxar ARD is not available with a sun elevation of less than 5 degrees (nighttime imagery). "view:sun_elevation": 54.1
hd boolean Indicates that HD imagery has been enabled for this selection. If HD imagery is not ordered or it is ordered in a restricted AOI, this field will not exist. "hd": true
hd_restricted_area_intersection boolean This will only appear if you've tried to request HD imagery in a restricted AOI. "hd_restricted_area_intersection": true

Proj: geometry and bbox examples

"proj:geometry": {
    "type": "Polygon",
    "coordinates": [
        [
            [472513.427734375, 3644718.9331054688],
            [472504.2724609375, 3639843.75],
            [475156.25, 3639843.75],
            [475156.25, 3644640.8081054688],
            [472513.427734375, 3644718.9331054688]
        ]
    ]
}
"proj:bbox": [472504.2724609375, 3639843.75, 475156.25, 3644718.9331054688]

The links object provides URLs to metadata files and shows their relationship to the file.

Field Description Example
rel The relationship between the link and the entity it describes. See "relationship" table below. "rel": "collection"
href The URL for the linked file. "href": "../../../acquisition_collections/104001006D0BB300_collection.json"
type The type for the linked file. "type": "application/json"

Relationship types

Type Description Example
collection URL to the acquisition collection file. "href": "../../../acquisition_collections/104001006D0BB300_collection.json"
parent URL to the acquisition collection file. "href": "../../../acquisition_collections/104001006D0BB300_collection.json"
root URL to the order collection file. "href": "../../../order_collections/5681790434919305322_root_collection.json"

Note: The "collection" and "parent" links go to the same file. Both are listed for STAC compliance and tool compatibility.

Assets object

The Assets object lists all of the downloadable files that are part of the order delivery. For some assets, additional metadata for the file is included here.

The asset list includes data masks and image files.

Data masks

Mask Asset name Description File type Filename
Cloud/Cloud Shadow Coverage Raster cloud-mask-raster Identifies clouds and cloud shadow pixels. raster {acquisitionID}-clouds.tif
Cloud Polygons cloud-mask Traces the boundaries of identified cloud polygons. vector {acquisitionID}-cloud-mask.gpkg
Cloud Shadow Polygons cloud-shadow-mask Traces the boundaries of identified cloud shadows. vector {acquisitionID}-cloud-shadow-mask.gpkg
Data Mask data-mask Identifies all pixels classified as "data" in the raster image and vectorizes those pixels as a GeoPackage. Pixels are either classified as "data" or "no data". vector {acquisitionID}-data-mask.gpkg
Healthy Vegetation Mask healthy-vegetation-mask-raster Binary raster indicating green, healthy vegetation pixels. raster {acquisitionID}-healthy-vegetation.tif
Healthy Vegetation Polygons healthy-vegetation-mask Polygons that indicate the detected boundaries of green, healthy vegetation. vector {acquisitionID}-healthy-vegetation-mask.gpkg
MS Pixel Saturation Mask ms-saturation-mask-raster Identifies saturated pixels in a 4 or 8-band multispectral image. raster {acquisitionID}-ms-saturation.tif
MS Pixel Saturation Polygons ms-saturation-mask Traces the boundaries of identified saturated pixels in a multispectral image. vector {acquisitionID}-ms-saturation-mask.gpkg
Pan Flare Mask pan-flare-mask-raster Detected flared pixels from panchromatic images. raster {acquisitionID}-pan-flare.tif
Pan Flare Polygons pan-flare-mask Polygons that indicate the detected boundaries of flares. vector {acquisitionID}-pan-flare-mask.gpkg
Terrain Shadows Mask terrain-shadow-mask-raster Identifies terrain shadow pixels. raster {acquisitionID}-terrain-shadows.tif
Terrain Shadows Polygon terrain-shadow-mask Traces the boundaries of detected terrain shadows. vector {acquisitionID}-terrain-shadow-mask.gpkg
Water Mask water-mask-raster Detects pixels for bodies of water and swimming pools. raster {acquisitionID}-water.tif
Water Polygons water-mask Traces the boundaries of bodies of water and swimming pools. vector {acquisitionID}-water-mask.gpkg

Note: Worldview-1 order deliveries include only the Cloud and Cloud Shadows masks.

Image files

Image file Asset Name Description Filename
Multispectral Image ms_analytic A 4 or 8-band multispectral image in GeoTiff format. {acquisitionID}-ms.tif
Panchromatic Image pan_analytic A single-band panchromatic image in GeoTiff format. {acquisitionID}-pan.tif
Visual Image visual An 8-bit image in GeoTiff format. {acquisitionID}-visual.tif

Note: The multispectral (ms_analytic) file is not delivered with WorldView-1 imagery.

Asset fields

Assets include the following fields:

Field name Description Example
type The file type. "type": "image/tiff; application=geotiff; profile=cloud-optimized"
title The title of the asset. The title is used to reference this file in documentation. "Cloud/Cloud Shadow Coverage Raster"
roles A standardized way to understand the type and intent of an asset. See asset roles. "roles": ["cloud","cloud-shadow"]
description A one-line description of the raster asset. Vector assets do not have a listed description. "thematic raster, 0 -> no data, 1 -> clear, 2 -> cloud, 3 -> cloud shadow"
href The URL reference for the asset. "href": "./104001006D0BB300-clouds.tif"

Additional raster metadata

Additional STAC metadata is list for raster assets. The descriptions are taken from the Projection and electro-optical STAC extension specifications.

Field name Type Description Example
proj:bbox number The bounding box of the Item in the asset CRS in 2 or 3 dimensions. "proj:bbox": [469843.75, 3639843.75, 475156.25, 3645156.25]
proj:shape integer The number of pixels in Y and X directions for the default grid. [2176, 2176]
proj:transform number The affine transformation coefficients for the default grid. [2.44140625, 0.0, 469843.75, 0.0, -2.44140625, 3645156.25, 0.0, 0.0, 1.0]
eo:bands object An array of available bands for the asset. [{"name": "BAND_CM","description": "Clouds/Cloud Shadows Mask"
raster:bands object Raster:bands classify data values in the Clouds and Cloud Shadows mask raster. {"value": 1,"name": "clear","description": "Clear of clouds or shadows"}

eo:bands

The eo:bands object lists the bands available for a particular image asset. This table lists eo band names associated with ARD image assets. Color bands are provided for multispectral imagery.

Spectral eo:bands

Maxar's multispectral imagery is captured with either 4 or 8 bands, depending on the sensor.

4-band multispectral imagery has the following bands:

band name common name description
BAND_B blue Blue
BAND_G green Green
BAND_R red Red
BAND_IR nir08 Near Infrared 1

8-band multispectral imagery has the following bands:

band name common name description
BAND_B blue Blue
BAND_C coastal Coastal blue
BAND_G green Green
BAND_R red Red
BAND_IR nir08 Near Infrared 1
BAND_Y yellow Yellow
BAND_RE rededge Red Edge 1
BAND_N2 nir09 Near Infrared 2

Panchromatic (black and white) imagery has a single band:

band name description
BAND_P pan

Visual RGB imagery has the following 3 bands:

band name common name description
BAND_R red Red
BAND_G green Green
BAND_B blue Blue

Visual panchromatic imagery has the following single band:

band name description
BAND_P_V Pan Visual

Raster Bands

The Cloud and Cloud Shadows mask raster asset has a set of raster bands.

value name description
0 nodata NoData
1 clear Clear of clouds or shadows
2 cloud Clouds
3 cloud_shadow Cloud shadows

Example 0rder STAC item metadata file

{
    "type": "Feature",
    "stac_version": "1.0.0",
    "stac_extensions": [
        "https://stac-extensions.github.io/view/v1.0.0/schema.json",
        "https://stac-extensions.github.io/projection/v1.0.0/schema.json",
        "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
        "https://stac-extensions.github.io/raster/v1.1.0/schema.json",
        "https://stac-extensions.github.io/grid/v1.0.0/schema.json",
        "https://stac-extensions.github.io/classification/v1.1.0/schema.json"
    ],
    "id": "38/120202332110/03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv",
    "properties": {
        "datetime": "2018-08-10 07:38:32Z",
        "platform": "WV04",
        "gsd": 0.36,
        "ard_metadata_version": "0.0.1",
        "catalog_id": "03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv",
        "utm_zone": 38,
        "quadkey": "120202332110",
        "view:off_nadir": 23.2,
        "view:azimuth": 130.9,
        "view:incidence_angle": 64.4,
        "view:sun_azimuth": 123.9,
        "view:sun_elevation": 68.0,
        "proj:epsg": 32638,
        "proj:geometry": {
            "type": "Polygon",
            "coordinates": [[[773061.5007680104, 3240156.25], [773090.2523345766, 3238957.8062060564], [772117.9930662059, 3238934.5298007736], [772088.7875557052, 3240156.25], [773061.5007680104, 3240156.25]]]
        },
        "grid:code": "MXRA-Z38-120202332110",
        "proj:bbox": [772088.7875557052, 3238934.5298007736, 773090.2523345766, 3240156.25],
        "tile:data_area": 1.1,
        "tile:clouds_area": 0.0,
        "tile:clouds_percent": 0
    },
    "bbox": [47.8, 29.25, 47.81, 29.26101900914853],
    "geometry": {
        "type": "Polygon",
        "coordinates": [[[47.81, 29.260808473224973], [47.81, 29.25], [47.8, 29.25], [47.8, 29.26101900914853], [47.81, 29.260808473224973]]]
    },
    "links": [
        {
            "rel": "collection",
            "href": "../../../acquisition_collections/03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv_collection.json",
            "type": "application/json"
        },
        {
            "rel": "parent",
            "href": "../../../acquisition_collections/03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv_collection.json",
            "type": "application/json"
        },
        {
            "rel": "root",
            "href": "../../../order_collections/20220711cbteststaceochangev1_root_collection.json",
            "type": "application/json"
        }
    ],
    "assets": {
        "data-mask": {
            "type": "application/geopackage+sqlite3",
            "title": "Data Mask",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-data-mask.gpkg",
            "roles": ["data-mask"]
        },
        "cloud-mask-raster": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "title": "Cloud/Cloud Shadow Coverage Raster",
            "description": "thematic raster, 0 -> no data, 1 -> clear, 2 -> cloud, 3 -> cloud shadow",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-clouds.tif",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [2176, 2176],
            "proj:transform": [2.44140625, 0.0, 769843.75, 0.0, -2.44140625, 3240156.25, 0.0, 0.0, 1.0],
            "raster:bands": [
                {
                    "classification:classes": [
                        {
                            "value": 0,
                            "name": "nodata",
                            "description": "NoData"
                        },
                        {
                            "value": 1,
                            "name": "clear",
                            "description": "Clear of clouds or shadows"
                        },
                        {
                            "value": 2,
                            "name": "cloud",
                            "description": "Clouds"
                        },
                        {
                            "value": 3,
                            "name": "cloud_shadow",
                            "description": "Cloud shadows"
                        }
                    ]
                }
            ],
            "roles": ["cloud", "cloud-shadow"]
        },
        "cloud-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-cloud-mask.gpkg",
            "title": "Cloud Polygons",
            "roles": ["cloud"]
        },
        "cloud-shadow-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-cloud-shadow-mask.gpkg",
            "title": "Cloud Shadow Polygons",
            "roles": ["cloud-shadow"]
        },
        "healthy-vegetation-mask-raster": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-healthy-vegetation.tif",
            "title": "Healthy Vegetation Mask",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [3741, 3741],
            "proj:transform": [1.4200748462977812, 0.0, 769843.75, 0.0, -1.4200748462977812, 3240156.25, 0.0, 0.0, 1.0],
            "roles": ["data"]
        },
        "healthy-vegetation-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-healthy-vegetation-mask.gpkg",
            "title": "Healthy Vegetation Polygons",
            "roles": ["data"]
        },
        "ms_analytic": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "title": "Multispectral Image",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-ms.tif",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [3741, 3741],
            "proj:transform": [1.4200748462977812, 0.0, 769843.75, 0.0, -1.4200748462977812, 3240156.25, 0.0, 0.0, 1.0],
            "eo:bands": [
                {
                    "name": "BAND_B",
                    "common_name": "blue",
                    "description": "Blue"
                },
                {
                    "name": "BAND_G",
                    "common_name": "green",
                    "description": "Green"
                },
                {
                    "name": "BAND_R",
                    "common_name": "red",
                    "description": "Red"
                },
                {
                    "name": "BAND_N",
                    "common_name": "nir08",
                    "description": "Near Infrared 1"
                }
            ],
            "roles": ["data"]
        },
        "ms-saturation-mask-raster": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "title": "Multispectral Pixel Saturation Mask",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-ms-saturation.tif",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [3741, 3741],
            "proj:transform": [1.4200748462977812, 0.0, 769843.75, 0.0, -1.4200748462977812, 3240156.25, 0.0, 0.0, 1.0],
            "roles": ["saturation"]
        },
        "ms-saturation-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-ms-saturation-mask.gpkg",
            "title": "MS Pixel Saturation Polygons",
            "roles": ["saturation"]
        },
        "pan_analytic": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "title": "Panchromatic Image",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-pan.tif",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [14964, 14964],
            "proj:transform": [0.3550187115744453, 0.0, 769843.75, 0.0, -0.3550187115744453, 3240156.25, 0.0, 0.0, 1.0],
            "eo:bands": [
                {
                    "name": "BAND_P",
                    "description": "Pan"
                }
            ],
            "roles": ["data"]
        },
        "pan-flare-mask-raster": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-pan-flare.tif",
            "title": "Pan Flare Mask",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [14964, 14964],
            "proj:transform": [0.3550187115744453, 0.0, 769843.75, 0.0, -0.3550187115744453, 3240156.25, 0.0, 0.0, 1.0],
            "roles": ["data"]
        },
        "pan-flare-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-pan-flare-mask.gpkg",
            "title": "Pan Flare Polygons",
            "roles": ["data"]
        },
        "terrain-shadow-mask-raster": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-terrain-shadows.tif",
            "title": "Terrain Shadow Mask",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [3741, 3741],
            "proj:transform": [1.4200748462977812, 0.0, 769843.75, 0.0, -1.4200748462977812, 3240156.25, 0.0, 0.0, 1.0],
            "roles": ["terrain-shadow"]
        },
        "terrain-shadow-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-terrain-shadow-mask.gpkg",
            "title": "Terrain Shadow Polygons",
            "roles": ["terrain-shadow"]
        },
        "visual": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "title": "Visual Image",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-visual.tif",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [17408, 17408],
            "proj:transform": [0.30517578125, 0.0, 769843.75, 0.0, -0.30517578125, 3240156.25, 0.0, 0.0, 1.0],
            "eo:bands": [
                {
                    "name": "BAND_R",
                    "common_name": "red",
                    "description": "Red"
                },
                {
                    "name": "BAND_G",
                    "common_name": "green",
                    "description": "Green"
                },
                {
                    "name": "BAND_B",
                    "common_name": "blue",
                    "description": "Blue"
                }
            ],
            "roles": ["visual"]
        },
        "water-mask-raster": {
            "type": "image/tiff; application=geotiff; profile=cloud-optimized",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-water.tif",
            "title": "Water Mask",
            "proj:bbox": [769843.75, 3234843.75, 775156.25, 3240156.25],
            "proj:shape": [3741, 3741],
            "proj:transform": [1.4200748462977812, 0.0, 769843.75, 0.0, -1.4200748462977812, 3240156.25, 0.0, 0.0, 1.0],
            "roles": ["water-mask"]
        },
        "water-mask": {
            "type": "application/geopackage+sqlite3",
            "href": "./03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv-water-mask.gpkg",
            "title": "Water Polygons",
            "roles": ["water-mask"]
        }
    },
    "collection": "03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv"
}
Back to top