ARD Order Deliveries¶

Last updated: December 1, 2022

Overview¶

Maxar's Analysis-Ready Data (ARD) is ordered by making a request to the Ordering API. The order request specifies the cloud storage location where the data should be delivered. We refer to the output of an order as an "ARD order delivery".

Contents of an order delivery¶

The output of a delivery is a time-series stack of tiles and their accompanying metadata. The files are:

A single-band panchromatic GeoTIFF.
A 4 or 8-band multispectral GeoTIFF.
A 3-band RGB GeoTIFF. We refer to this file as a "visual" tile.
A set of data masks delivered individually in both raster GeoTIFF and vector GeoPackage formats. Individual masks can be excluded from the delivery as part of the order requests.
A set of STAC-compliant metadata files that describe the contents of the order delivery.

Delivery file directory structure¶

ARD orders are delivered in the following directory structure:

📁 {bucket or container}
└── 📁 {prefix (optional)}
    └── 📁 acquisition_collections
        └─╴📄 {acquisitionID}_collection.json
    └── 📁 order_collections
        └─╴📄 {orderID}_root_collection.json
    └── 📁 {UTM-zone}
        └── 📁 {quadkey}
            └── 📁 {acquisition-date}  
                └─╴📄 (files)
    └── 📄 {orderID}-request.json

If a prefix is not submitted with the order request, the files will be delivered directly to the bucket location.
There can be multiple prefixes in the path.
The UTM zone and quadkey indicate where the tile is located on the grid.
The acquisition date is the month, day, and year the image was acquired by the satellite. In a list view, the acquisition-date folders are arranged from oldest to most recent. The image files and accompanying data are stored in the acquisition date folder.

See About the Directory Structure for details.

Non-intersecting tiles report¶

Most orders will not include a non-intersecting tiles report file.

The imagery selection and order validation steps use an estimated image footprint, based on metadata. The estimated footprint and the actual footprint can be slightly different. Most of the time, the difference doesn't impact the ordering process.

Occasionally, when only the edge of the estimated footprint intersects with the AOI, the shift is enough that the actual footprint does not intersect. In this scenario, the imagery would pass select and order validation, but the non-intersecting tile or tiles cannot be ordered. When this occurs, the intersecting image tiles in the order are delivered, and a report is generated that lists the non-intersecting tiles that could not be delivered.

The report is named {orderID}_non_intersecting_tiles_report.json.

It is located in the order_collections subdirectory.

📁 {bucket or container}
└── 📁 {prefix}
    └── 📁 acquisition_collections
        └─╴📄 {acquisition ID}_collection.json
    └─╴ 📁 order_collections
        └─╴📄 {orderID}_root_collection.json
        └─╴📄 {orderID}_non_intersecting_tiles_report.json

Image files¶

There are three raster image files for each tile in a delivery. These are cloud-optimized GeoTiffs, or "COGs". Click the image file link for more details about each image type.

Image file	Description	Filename
multispectral image	A 4 or 8-band multispectral image in GeoTiff format.	{acquisitionID}-ms.tif
panchromatic image	A single-band panchromatic image in GeoTiff format.	{acquisitionID}-pan.tif
visual (RGB) image	A 3-band RGB image in GeoTiff format.	{acquisitionID}-visual.tif

See About ARD for more information about ARD image tiles and additional pre-processing steps.

Data Masks¶

ARD order deliveries include a set of data masks for each tile. A raster GeoTiff (.tif) and a vector GeoPackage (.gpkg) file are delivered for most masks. There are two exceptions:

Clouds and cloud shadows are both captured in a single raster mask called the "cloud/cloud shadow coverage raster". Cloud and cloud shadows have individual vector files, named "cloud polygons" and "cloud shadow polygons".
The "data mask" is derived from the raster image and is delivered only as a vectorized GeoPackage.

The mask names in the table can be clicked for additional documentation and imagery examples. There is no additional documentation for the "data mask" which simply identifies pixels with data.

Mask	Description	File type	Filename
Cloud/Cloud Shadow Coverage Raster	Identifies clouds and cloud shadow pixels.	raster	{acquisitionID}-clouds.tif
Cloud Polygons	Traces the boundaries of identified cloud polygons.	vector	{acquisitionID}-cloud-mask.gpkg
Cloud Shadow Polygons	Traces the boundaries of identified cloud shadows.	vector	{acquisitionID}-cloud-shadow-mask.gpkg
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	Binary raster indicating green, healthy vegetation pixels.	raster	{acquisitionID}-healthy-vegetation.tif
Healthy Vegetation Polygons	Polygons that indicate the detected boundaries of green, healthy vegetation.	vector	{acquisitionID}-healthy-vegetation-mask.gpkg
MS Pixel Saturation Mask	Identifies saturated pixels in a 4 or 8-band multispectral image.	raster	{acquisitionID}-ms-saturation.tif
MS Pixel Saturation Polygons	Traces the boundaries of identified saturated pixels in a multispectral image.	vector	{acquisitionID}-ms-saturation-mask.gpkg
Pan Flare Mask	Detected flared pixels from a panchromatic image.	raster	{acquisitionID}-pan-flare.tif
Pan Flare Polygons	Traces the boundaries of detected flare pixels from a panchromatic image.	vector	{acquisitionID}-pan-flare-mask.gpkg
Terrain shadows mask	Identifies terrain shadow pixels.	raster	{acquisitionID}-terrain-shadows.tif
Terrain Shadows Polygon	Traces the boundaries of detected terrain shadows.	vector	{acquisitionID}-terrain-shadow-mask.gpkg
Water Mask	Detects pixels for bodies of water and swimming pools.	raster	{acquisitionID}-water.tif
Water Polygons	Traces the boundaries of bodies of water and swimming pools.	vector	{acquisitionID}-water-mask.gpkg

Metadata files¶

An ARD order delivery includes additional files with information about the order and its contents. The metadata files adhere to the Spatio-temporal Asset Catalog (STAC) specifications.

Click a filename to learn more about the contents of a specific file.

File	Description	File type	Filename
STAC item metadata file	Describes the ordered tile and its assets.	JSON	{acquisitionID}.json
Order STAC collection file	Describes the contents of the order delivery.	JSON	/order_collections/{orderID}_root_collection.json
Acquisition STAC collection file	Describes the acquisitions in the order delivery.	JSON	/acquisition_collections/{acquisitionID}_collection.json
Order request file	Shows the JSON body of the order request.	JSON	/{orderID}-request.json