Skip to content

ARD Order Deliveries

Last updated: June 15, 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
Back to top