Skip to main content

STAC Item Metadata


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

ExtensionTypeField name prefixDescription
electro-opticalSTACeoData 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.
ProjectionSTACprojDescribes items whose assets are in a geospatial projection.
View GeometrySTACviewAdds metadata related to angles of sensors and other radiance angles that affect the view of resulting data.
RasterSTACrasterDescribes raster assets at band level (one or multiple).
GridSTACgridProvides fields related to gridded data products.
ClassificationSTACclassificationUsed 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.
tilecustomtileData 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.

FieldTypeDescriptionExample
typestringThe type of the GeoJSON object. The type for a STAC item is "feature"."type": "Feature"
stac_versionstringThe STAC version used by the item."stac_version": "1.0.0"
stac_extensionsstringExtensions 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"]
idstringThe unique identifier for an item. The ID for the ARD item is utm_zone/quadkey/acquisitionID."id": "11/031311311232/104001006D0BB300"
bboxnumberThe bounding box coordinates for the item, projected to wgs84."bbox": [-117.29404086049149, 32.89643160060904, -117.26563783226379, 32.94040782110711]
geometryGeoJSON geometry objectThe geometry coordinates for the polygon, projected to wgs84."geometry": {"type": "Polygon","coordinates": [[coordinates listed here]]}
propertiesobjectAdditional metadata for the item.See Properties table below.
linksobjectA list of links to resources and additional URLs.See Links table below.
assetsobjectA list of assets and their metadata. Assets are downloadable objects for the item.See Assets table below.
collectionstringThe 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.

FieldTypeDescriptionExample
datetimestringAn 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"
platformstringThe satellite that acquired the image."platform": "WV03"
gsdnumberThe spatial resolution, or ground sampling distance, of the sensor that acquired the image, stated in meters."gsd": 0.32
ard_metadata_versionstringThe version number assigned to ARD metadata."ard_metadata_version": "0.0.1"
catalog_idstringThe unique identifier for the item. This is also referred to as the "acquisition ID"."catalog_id": "104001006D0BB300"0
utm_zonenumberThe Universal Transverse Mercator(UTM) coordinate system number assigned to the zone where the item is located."utm_zone": 11
proj:epsgintegerThe coordinate reference system used by the asset data. ARD uses "epsg"."proj:epsg": 32611
proj: geometryGeoJSON geometry objectDefines the footprint of this Item in native UTM projection.see example below this table.
proj:bboxnumberBounding box of the Item in the asset coordinate reference system (CRS), in 2 or 3 dimensions; native UTM projection.see example below this table.
quadkeystringThe address where the item is located on the Maxar grid."quadkey": "031311311232"
tile:data_areanumberThe square kilometer area of the tile with data."tile:data_area": 12.8
tile:clouds_areanumberThe square kilometer area of the tile that has clouds."tile:clouds_area": 0
tile:clouds_percentnumberThe percentage of the tile that is covered by clouds."tile:clouds_percent": 0
view:off_nadirnumberThe angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90)."view:off_nadir": 13.0
view:azimuthnumberViewing 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_anglenumberThe 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_azimuthnumberSun 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_elevationnumberSun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (-90-90). ARD is not available with a sun elevation of less than 5 degrees (nighttime imagery)."view:sun_elevation": 54.1
hdbooleanIndicates 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_intersectionbooleanThis 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.

FieldDescriptionExample
relThe relationship between the link and the entity it describes. See "relationship" table below."rel": "self"
hrefThe URL for the linked file."href": "https://ard.maxar.com/api/v1/metadata/cells/"Z13-031133320302/acquisitions?format=stac"

Relationship types

TypeDescriptionExample
collectionURL to the acquisition collection file."href": "../../../acquisition_collections/104001006D0BB300_collection.json"
parentURL to the acquisition collection file."href": "../../../acquisition_collections/104001006D0BB300_collection.json"
rootURL 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

MaskAsset nameDescriptionFile typeFilename
Cloud/Cloud Shadow Coverage Rastercloud-mask-rasterIdentifies clouds and cloud shadow pixels.raster{acquisitionID}-clouds.tif
Cloud Polygonscloud-maskTraces the boundaries of identified cloud polygons.vector{acquisitionID}-cloud-mask.gpkg
Cloud Shadow Polygonscloud-shadow-maskTraces the boundaries of identified cloud shadows.vector{acquisitionID}-cloud-shadow-mask.gpkg
Data Maskdata-maskIdentifies 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 Maskhealthy-vegetation-mask-rasterBinary raster indicating green, healthy vegetation pixels.raster{acquisitionID}-healthy-vegetation.tif
Healthy Vegetation Polygonshealthy-vegetation-maskPolygons that indicate the detected boundaries of green, healthy vegetation.vector{acquisitionID}-healthy-vegetation-mask.gpkg
MS Pixel Saturation Maskms-saturation-mask-rasterIdentifies saturated pixels in a 4 or 8-band multispectral image.raster{acquisitionID}-ms-saturation.tif
MS Pixel Saturation Polygonsms-saturation-maskTraces the boundaries of identified saturated pixels in a multispectral image.vector{acquisitionID}-ms-saturation-mask.gpkg
Pan Flare Maskpan-flare-mask-rasterDetected flared pixels from panchromatic images.raster{acquisitionID}-pan-flare.tif
Pan Flare Polygonspan-flare-maskPolygons that indicate the detected boundaries of flares.vector{acquisitionID}-pan-flare-mask.gpkg
Terrain Shadows Maskterrain-shadow-mask-rasterIdentifies terrain shadow pixels.raster{acquisitionID}-terrain-shadows.tif
Terrain Shadows Polygonterrain-shadow-maskTraces the boundaries of detected terrain shadows.vector{acquisitionID}-terrain-shadow-mask.gpkg
Water Maskwater-mask-rasterDetects pixels for bodies of water and swimming pools.raster{acquisitionID}-water.tif
Water Polygonswater-maskTraces 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 fileAsset NameDescriptionFilename
Multispectral Imagems_analyticA 4 or 8-band multispectral image in GeoTIFF format.{acquisitionID}-ms.tif
Panchromatic Imagepan_analyticA single-band panchromatic image in GeoTIFF format.{acquisitionID}-pan.tif
Visual ImagevisualAn 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 nameDescriptionExample
typeThe file type."type": "image/tiff; application=geotiff; profile=cloud-optimized"
titleThe title of the asset. The title is used to reference this file in documentation."Cloud/Cloud Shadow Coverage Raster"
rolesA standardized way to understand the type and intent of an asset. See asset roles."roles": ["cloud","cloud-shadow"]
descriptionA 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"
hrefThe 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 nameTypeDescriptionExample
proj:bboxnumberThe 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:shapeintegerThe number of pixels in Y and X directions for the default grid.[2176, 2176]
proj:transformnumberThe 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:bandsobjectAn array of available bands for the asset.[{"name": "BAND_CM","description": "Clouds/Cloud Shadows Mask"
raster:bandsobjectRaster: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 namecommon namedescription
BAND_BblueBlue
BAND_GgreenGreen
BAND_RredRed
BAND_IRnir08Near Infrared 1

8-band multispectral imagery has the following bands:

band namecommon namedescription
BAND_BblueBlue
BAND_CcoastalCoastal blue
BAND_GgreenGreen
BAND_RredRed
BAND_IRnir08Near Infrared 1
BAND_YyellowYellow
BAND_RErededgeRed Edge 1
BAND_N2nir09Near Infrared 2

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

band namedescription
BAND_Ppan

Visual RGB imagery has the following 3 bands:

band namecommon namedescription
BAND_RredRed
BAND_GgreenGreen
BAND_BblueBlue

Visual panchromatic imagery has the following single band:

band namedescription
BAND_P_VPan Visual

Raster Bands

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

valuenamedescription
0nodataNoData
1clearClear of clouds or shadows
2cloudClouds
3cloud_shadowCloud shadows

Example order 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/20220711v1_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"
}