Analysis-Ready Data (ARD)
Overview
Maxar Analysis-Ready Data (ARD) offers a cloud-native bundle of time-series stacks of imagery with specific pre-processing steps completed. ARD imagery deliverables include three Cloud-Optimized GeoTIFF files. These three files are an RGB image for visualization, a panchromatic image, and a 4 or 8-band multispectral image. Accompanying each tile in an order is a set of data masks in raster and vector formats. The files are then cataloged using static Spatio-Temporal Asset Catalog files. See About ARD for details.
Ordering Analysis-ready imagery
This documentation describes the requirements that are specific for ordering analysis-ready imagery. To see the full description of an order request, see the Ordering API Guide.
When you place an order for analysis-ready data, you will:
- include the
nameand thenamespacein the URL path. - include the
settingsobject for the pipeline in the order request body.
| Content Type | Namespace | Name |
|---|---|---|
| Analysis-Ready Data (ARD) | imagery | analysis-ready |
Supported requests
Base URL: https://api.maxar.com
| Request Type | Path | Description |
|---|---|---|
| Place an order | POST /ordering/v1/pipelines/imagery/analysis-ready/order | Places an order to the ARD content pipeline. |
| Validate order | POST /ordering/v1/pipelines/imagery/analysis-ready/validate | Verifies that the request json is formatted correctly and that the settings are valid. Also returns estimated usage data. |
| Estimate usage | POST /ordering/v1/pipelines/imagery/analysis-ready/estimate | Returns estimated usage for the order. |
| Get the details of an order | GET /ordering/v1/orders/{id} | Submit an order ID to view the order's details and status information. |
| Cancel an order | POST /ordering/v1/orders/{id}/cancel | Submit an order ID to cancel the order before the delivery process begins. |
Place an order
Request URL
An Order request URL requires a "namespace" and a "name. These tell the Ordering API what product to order.
POST https://api.maxar.com/ordering/v1/pipelines/{namespace}/{name}/order
For ARD, these are:
- Namespace:
imagery - Name:
analysis-ready
POST https://api.maxar.com/ordering/v1/pipelines/imagery/analysis-ready/order
This document describes the parts of the ordering process that are specific to an ARD order. The full ordering process is described in the Intro to Ordering.
Content-specific settings
When placing an order, some information is specific to the type of content selected. This information is grouped together as "settings".
Note: WorldView Legion imagery cannot be ordered as ARD tiles at this time.
| Parameter | Required | Description | Example |
|---|---|---|---|
| acquisitions | required | One or more acquisition IDs to order. May be constrained by an Area of Interest (AOI) and/or a cell ID. | "acquisitions": ["10300100B3841C00", "10300100AC700900"] |
| cells | optional | The cell ID is made up of the UTM zone and quadkey address of the grid cell. | "cells": ["Z47-122220121320"] |
| aoi | optional | A GeoJSON geometry or feature collection. | See ordering request example. |
| ard_settings | optional | Change the default value for one or more ARD settings. If the ard_settings object is not included, the default values for each item will be used. | "ard_settings": { "bundle_adjust": true} |
The ard_settings object controls a set of data masks and processes that can be turned on or off. Each item controlled within the object has a default value. The default values can be overridden by including them in the ard_settings object. Any fields not included in ard_settings will retain their default values. If the ard_settings object is not included, all default values will be used.
| setting | description | default value |
|---|---|---|
bundle_adjust | Determines whether Bundle Block Adjustment (BBA) is run. | false |
hd | Determines whether HD technology is run. | false |
cloud_mask | Determines whether the cloud/cloud shadows raster and vector masks are delivered. | true |
healthy_vegetation_mask | Determines whether the healthy vegetation raster and vector masks are delivered. | true |
ms_saturation_mask | Determines whether the multispectral saturation raster and vector masks are delivered. | true |
pan_flare_mask | Determines whether the panchromatic flare raster and vector masks are delivered. | true |
terrain_shadow_mask | Determines whether the terrain shadow raster and vector masks are delivered. | true |
water_mask | Determines whether the water raster and vector masks are delivered. | true |
Example settings object
"settings": {
"acquisitions": ["03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv"],
"aoi": {
"type": "Polygon",
"coordinates": [
[
[47.8, 29.25],
[47.8, 29.27],
[47.81, 29.27],
[47.81, 29.25],
[47.8, 29.25]
]
]
},
"ard_settings": {
"bundle_adjust": true,
"healthy_vegetation_mask": false,
"water_mask": false
}
},
Example ARD order
{
"settings": {
"acquisitions": ["03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv"],
"aoi": {
"type": "Polygon",
"coordinates": [
[
[47.8, 29.25],
[47.8, 29.27],
[47.81, 29.27],
[47.81, 29.25],
[47.8, 29.25]
]
]
},
"ard_settings": {
"bundle_adjust": true,
"healthy_vegetation_mask": false,
"water_mask": false
}
},
"output_config": {
"amazon_s3": {
"bucket": "example-bucket",
"prefix": "example-prefix"
}
},
"notifications": [{
"type": "email",
"target": "email@myemail.com",
"level": "FINAL_ONLY"
}],
"metadata": {
"project_id": "onboarding"
}
}
See the Outputs and Notifications guides for more information on these sections of the order payload.
Example ARD order response
{
"data": {
"id": "99926034175760632",
"date_created": "2022-12-01T23:19:02Z",
"date_modified": "2022-12-01T23:19:04Z",
"user_id": "144445555",
"pipeline_id": "imagery/analysis-ready",
"settings": {
"acquisitions": ["03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv"],
"aoi": {
"type": "Polygon",
"coordinates": [
[
[47.8, 29.25],
[47.8, 29.27],
[47.81, 29.27],
[47.81, 29.25],
[47.8, 29.25]
]
]
},
"ard_settings": {
"bundle_adjust": true,
"healthy_vegetation_mask": false,
"water_mask": false
}
},
"output_config": {
"amazon_s3": {
"bucket": "example-bucket",
"prefix": "example-prefix"
}
},
"notifications": [
{
"type": "email",
"target": "email@myemail.com",
"level": "FINAL_ONLY"
}
],
"metadata": {
"project_id": "your project name"
},
"status": "RECEIVED",
"status_details": {},
"process_details": {},
"order_links": {
"order_details_url": "https://api.maxar.com/ordering/v1/orders/99926034175760632",
"order_events_url": "https://api.maxar.com/ordering/v1/orders/99926034175760632/events"
}
},
"links": {
"request": "https://api.maxar.com/ordering/v1/pipelines/imagery/analysis-ready/order"
},
"request_timestamp": "2022-12-01T23:19:02Z",
"response_timestamp": "2022-12-01T23:19:06Z",
"request_duration": 4.0
}
Validate an order request
To validate your order before placing it, send your request body to the `/validate`` endpoint first.
POST https://api.maxar.com/ordering/v1/pipelines/imagery/analysis-ready/validate
This will verify that your request is formatted correctly and contains the required settings and allowed values for those settings. For ARD a /validate response also includes estimated usage data.
Validate order example 200
Status: 200 OK
{
"data": {
"message": "Order dry-run validation successful.",
"usage": [
{
"product_id": 242,
"units": "sqkm",
"quantity": 0,
"description": "Fresh Archive Imagery < 90 Days"
},
{
"product_id": 244,
"units": "sqkm",
"quantity": 3,
"description": "Standard Archive Imagery ≥ 90 Days"
}
]
},
"links": {
"request": "https://api.maxar.com/ordering/v1/pipelines/imagery/analysis-ready/validate"
},
"request_timestamp": "2023-10-10T22:00:34Z",
"response_timestamp": "2023-10-10T22:00:37Z",
"request_duration": 3.0
}
Validate order example 400
In this example, the order did not pass validation because a field name was incorrect.
Status: 400 Bad Request
{
"links": {
"request": "https://api.maxar.com/ordering/v1/pipelines/imagery/analysis-ready/validate"
},
"request_timestamp": "2023-10-10T22:08:40Z",
"response_timestamp": "2023-10-10T22:08:40Z",
"request_duration": 0.0,
"error": {
"error_code": "invalid_request_body",
"error_type": "invalid_request_error",
"error_messages": [
"$: Additional properties are not allowed ('acquisitionID' was unexpected)",
"$: 'acquisitions' is a required property"
]
}
}
Get a usage estimate
Get a usage estimate for the order
Status: 200 OK
{
"data": {
"usage_estimate": [
{
"pipeline_id": "imagery/analysis-ready",
"metrics": [
{
"units": "sqkm",
"quantity": 0,
"description": "Fresh Archive Imagery < 90 Days",
"usage_details": {}
}
],
"product_id": 242,
"date_reported": "2023-10-10T22:12:12Z"
},
{
"pipeline_id": "imagery/analysis-ready",
"metrics": [
{
"units": "sqkm",
"quantity": 3,
"description": "Standard Archive Imagery ≥ 90 Days",
"usage_details": {}
}
],
"product_id": 244,
"date_reported": "2023-10-10T22:12:12Z"
}
],
"order_config": {
"pipeline_id": "imagery/analysis-ready",
"settings": {
"acquisitions": [
"03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv"
],
"aoi": {
"type": "Polygon",
"coordinates": [
[
[
47.8,
29.25
],
[
47.8,
29.27
],
[
47.81,
29.27
],
[
47.81,
29.25
],
[
47.8,
29.25
]
]
]
},
"ard_settings": {
"bundle_adjust": true,
"healthy_vegetation_mask": false,
"water_mask": false
}
},
"output_config": {
"amazon_s3": {
"bucket": "example-bucket",
"prefix": "example-prefix"
}
},
"notifications": [
{
"type": "email",
"target": "email@myemail.com",
"level": "INTERMEDIATE"
}
],
"metadata": {
"project_id": "onboarding"
}
}
},
"links": {
"request": "https://api.maxar.com/ordering/v1/pipelines/imagery/analysis-ready/estimate"
},
"request_timestamp": "2023-10-10T22:12:05Z",
"response_timestamp": "2023-10-10T22:12:12Z",
"request_duration": 7.0
}
Get order status
Once an order is placed, you can monitor its status or review the details of your order by making the following request with your order ID.
POST
https://api.maxar.com/ordering/v1/orders/:id
The id was returned in the response body to your order request. It can also be found in your notifications.
Cancel an order
Once an order is placed, you can monitor its status or review the details of your order by making the following request with your order ID.
POST
https://api.maxar.com/ordering/v1/orders/:id
The id was returned in the response body to your order request. It can also be found in your notifications.