May 2022 ARD Release Announcement¶
New features and updates¶
The latest Maxar ARD release includes the following features and updates:
Deprecation announcements¶
There are two ARD changes in this release that replace legacy components. The legacy components will be removed on July 12, 2022. Read the Deprecation Announcement for details.
-
Ordering API: The
bundle_adjust
field is now part of the new order "settings" section. In 60 days, the top-levelbundle_adjust
field will be removed from the order request. -
Order STAC item file: The
eo:bands
field will be removed from mask rasters.
The Maxar ARD Dashboard User Interface¶
Last fall we introduced the Maxar ARD Dashboard, with capabilities for managing accounts (admins only), and viewing usage and order data. With today's release, you can now explore ARD metadata grid cell coverage, select imagery, and place orders using the ARD Dashboard.
-
Access the Maxar ARD Dashboard
-
Sign in using your ARD credentials (email and password)
-
Get answers to your Dashboard questions from the new ARD Dashboard Help Center
Temporal/Seasonal Queries¶
Based on customer feedback, we've added temporal query fields that can be used to create seasonal queries. Because seasons are different in different locations, you'll use the following fields to create your own queries:
collect_month
collect_month_day
collect_day
This example combines the datetime
field and the query:collect_month_day
field to look for imagery captured only between 12-21 and 02-03, starting with 2017 and ending December 31, 2020 (excluding 2021).
{
"datetime": "2017/2021",
"bbox": [-106.8, 35.1, -106.4, 35.4],
"stack_depth": 3,
"query": {
"collect_month_day": {
"or": [{
"gte": "12-21"
},
{
"lte": "02-03"
}
]
},
"aoi:cloud_free_percentage": {
"gte": 95.0
},
"aoi:data_percentage": {
"gte": 75.0
},
"view:off_nadir": {
"lt": 30
},
"view:sun_elevation": {
"gte": 5
}
}
}
The Temporal Queries documentation provides examples for creating temporal ranges, along with examples of seasonal ranges by hemisphere. These fields can also be combined with the datetime
field or image_age_category
field to further filter your results.
WorldView-1 Imagery can now be ordered as Analysis-Ready Data¶
WorldView-1 imagery can now be ordered as ARD. A WorldView-1 order delivery includes a panchromatic GeoTIFF, 1-band Pan "visual" GeoTIFF, a STAC item metadata file, and a subset of masks. WorldView-1 is not included in select, explore, or monitoring requests by default. It must be explicitly requested.
New Order Settings Section¶
A new optional "settings" section has been added to order requests. This section includes order processing settings that can be turned on or off.
Masks are now Optional¶
ARD order deliveries come with a set of data masks by default. You can now opt out of specific masks. All masks are optional except for the "Data Mask".
All masks are still delivered by default. To opt out of one or more masks, you'll add them to the "settings" section, and set the masks' value to "false."
Bundle Block Adjustment is part of Settings¶
The bundle_adjust
field, which is used to run the Bundle Block Adjustment (BBA) process is now part of the "settings" section. This field is off by default. To run BBA, include this field in the settings section with a value of "true".
Legacy bundle_adjust field 60 day deprecation period¶
The bundle_adjust
setting in the top level request will be removed on July 12, 2022. Because this is a potentially breaking change, we will support using this field in the top level request or the settings section until the 60 day period ends.
If you are using the bundle_adjust
field to run Bundle Block Adjustment on your orders, we recommend that you stop using the top-level bundle_adjust
field, and start using the bundle_adjust
field in settings now. We will support both fields until July 12, 2022.
Example order settings¶
This example shows the new "settings" section. The bundle_adjust
field for running Bundle Block Adjustment (BBA) is also now part of this section. This example would run BBA and exclude the Panchromatic Flare Mask.
{
"acquisitions": [
{
"id": "10300100B2B49700",
"cell_ids": ["Z13-031133320203"]
}
],
"bbox": [-106.8, 35.1, -106.4, 35.4],
"settings": {
"bundle_adjust": true,
"pan_flare_mask": false
},
"output_config": {
"amazon_s3": {
"bucket": "user-docs-demo",
"prefix": "abq_04-2022"
}
},
"notifications": [{
"type": "email",
"address": "shea.barnes@myemail.com"
}]
}
Thumbnail Image Support¶
The "Browse" API endpoint for retrieving and previewing tile thumbnail images is now available and documented. You'll need the acquisition ID and the cell ID to make the request.
GET https://ard.maxar.com/api/v1/browse/preview/{acquisition_ID}/{cell_id}
https://ard.maxar.com/api/v1/browse/preview/10300100B39ACD00/Z13-031133320013
Example:
See Preview Tile Thumbnail Guide
New order "Metadata" field for tracking information associated with the request¶
We've added a new field for order requests where you can track information about the order. For example, if you are placing orders for a specific project, you can include the project name in this field. The field accepts any type of value, and it can accept nested fields.
See Optional Field for additional tracking data.
Select API Responses are now Asynchronous¶
We've updated the Select API to always return an asynchronous response to a POST /select
request. This means:
-
The success response code has changed from
200 OK
to202 Accepted
. -
It will always return a status, an ID, and a link to get the details of the selection.
-
You will make a
GET
request with the select ID to get the details, such as acquisition count, stack depth fulfillment, and estimated usage.
See Select Results Documentation
Updated Select STAC file¶
We've made the following changes to the Select STAC item file to adhere to the STAC specification and to improve readability:
-
updated the STAC version to 1.0.0, with minor changes to conform to that version's requirements
-
updated the output to conform to STAC single-file catalog extension
-
removed links to non-existent assets
-
Added a "preview" asset link for each STAC item in the collection
Updated Order STAC Item Metadata File¶
Grid metadata¶
ARD tiles items now include the grid:code
field from the Grid Extension. This extension provides a normalized way to present grid cell identifiers.
Classification Values¶
Classification values for the cloud mask raster are now described using the Classification Extension. This allows clients and software libraries to understand the what the four classes in the cloud mask raster represent.
Asset roles¶
All assets now have asset roles. Using roles provides a standardized way to understand the type and intent of an asset.
Deprecating in 60 days:¶
The field eo:bands
will be removed from mask rasters. It currently provides information that is duplicated in the asset itself and does not match the intent of the EO extension.