Get Started with Maxar ARD¶
Last Updated: August 12, 2022
Maxar Analysis Ready Data (ARD) offers time-series stacks of imagery with specific pre-processing steps completed. To learn more about the Maxar ARD imagery, see about ARD.
ARD is available for Maxar's GeoEye-1, WorldView-1, WorldView-2, WorldView-03 VNIR, and WorldView-4 satellite archives. ARD imagery includes three GeoTIFFs: a 3-band RGB image for visualization, a panchromatic image, and a 4 or 8-band multispectral image. A set of data masks in raster and vector formats accompanies each tile in an order delivery by default. Individual masks can be excluded from the delivery.
Note: Worldview-1 orders include a subset of the ARD assets. See WorldView-1 imagery for details.
ARD imagery is selected and ordered via the ARD API. The resulting files from an order are saved to the cloud storage platform you specify during the ordering process. Supported cloud storage platforms are Amazon S3, Microsoft Azure Blob Storage, and Google Cloud storage.
Selecting imagery¶
Imagery can be selected by sending a request body with a set of criteria to one of two imagery selection APIs. The request body can include an AOI, a date range, and additional query criteria. If you already have a list of acquisition IDs you obtained from a different source, you can also use those to select relevant tiles out of them.
The Cell Metadata API¶
The Cell Metadata API takes a request body and returns a list of matching acquisitions and cells. It's ideal for those who have smaller AOIs and want fast and simple results.
The Cell Metadata API takes a request body and returns metadata about tiles matching your criteria in a variety of useful formats: a GeoJSON feature collection, a STAC single-document collection, or a simple list of acquisition and cell IDs. Results are returned in order from newest to oldest.
There are two ways to use the results of a Cell Metadata query to place an order:
-
Query ID: The
query_idcan be submitted in theselect_idfield of an order request. This will order the acquisitions and cells that match the query criteria. -
Order by acquisitions: If the results are returned in "order" format, the list of acquisitions and cell IDs can be copied and pasted into the order request body.
The Select API¶
The Select API accepts a request body and returns a detailed set of information about the selection in the response to a "Get Select Details" request.
A request to the Select API returns a copy of the request and the following information:
-
the total number of acquisitions in the order
-
a stack depth summary for the cells in the selection
-
estimated cost and area usage for the selection
-
a set of links to files that provide information about the selection, including an html visualization file
The result are sorted based on which cells best fit the criteria specified in your request.
You can order the results of your selection by placing the "ID" from the select response in the "select_id" field in an order request.
Note: ARD usage costs are incurred only when an order is placed and delivered successfully. There is no charge for the process of selecting imagery. Estimated area and usage data may be slightly higher than actual data.
Select and visualize tiles in the ARD Dashboard¶
The Maxar ARD Dashboard user interface lets you submit an AOI and additional selection criteria, and view the resulting tiles from the selection. You can remove any tiles you don't want and then order the remaining tiles from your cart.
Ordering imagery¶
Imagery can be ordered by submitting the "select" or "query" ID from the results of an imagery selection request or by listing the acquisitions you want to order. You can optionally include a list of cell IDs with the acquisitions and constrain the request area by an AOI. The acquisitions and AOI must intersect.
An order request also includes:
-
cloud store location (required): This is the cloud storage location where the order will be delivered. ARD supports deliveries to Amazon S3, Azure Blob Storage, and Google Cloud Storage.
-
a "dry run" setting (optional): The dry run setting lets you validate an order before submitting it. This verifies that ordered imagery can be written to the specified cloud storage location and checks for common errors.
-
a "settings" section (optional): Use this section to turn on Bundle Block Adjustment (BBA) or turn off masks you don't want delivered. If settings are not used, all masks are delivered, and BBA is turned off.
-
an order status notification method (optional): Order status notifications can be configured to send by email or as SNS topics (SNS topics are applicable to Amazon S3 users only).
Order processing times¶
An imagery order can take 1-3 days to process. Running BBA may increase order processing time.
ARD sample dataset¶
The Maxar ARD sample dataset provides a working example of the output files from an imagery order. The sample dataset lets you view, download, and try out ARD imagery. It can be used with the CLI, SDK, and any other tool that can read cloud-optimized GeoTIFFs (COGs).
View sample data and download selected files.
Download sample data from s3://maxar-ard-samples/v3/sample-002 and use it.
Tools for interacting with the ARD API¶
Maxar offers multiple ways to interact with the ARD API.
• a Python SDK
• a Command Line Interface (CLI)
• a Postman collection for direct API requests
• the ARD Dashboard
The SDK and CLI provide additional support and examples using ARD data. You may find these tools preferable to direct API access. For direct API access, we recommend using the Postman client with our Postman collection.
For a general overview of these tools, see Introduction to ARD developer tools
For SDK and CLI documentation, see ARD SDK Docs
ARD Step-by-Step¶
Quickstart examples are provided at the end of this section using the Python SDK, the ARD CLI, and direct API requests.
1. Get an access token¶
The ARD API uses an OAuth access token for authentication. To request a token, you'll send your ARD username (email address) and password to the "authenticate" endpoint. Tokens expire after twelve hours and must be requested again. If you are using the Python SDK or the ARD CLI, you'll add your credentials to an .ini file and a new token will be fetched each time you log in.
To learn how to request a token, see Get an access token.
To change your password, enter your email address into the ARD password form.
2. Give Maxar ARD Write Access to your cloud storage location¶
When you place an order for ARD, the tiles and accompanying data will be delivered to your personal cloud storage location. In order to deliver the files, Maxar ARD needs permission to write to your bucket.
S3 users, to grant permission, you'll need to add a bucket policy. See Set up an S3 bucket policy for instructions.
Azure and Google cloud storage users, you'll create temporary credentials for your specified platform. You will either save them to the ARD credentials service (account administrators only) or send a temporary URL with the order. See Ordering ARD Imagery and ARD Credentials Service.
3. Select ARD imagery to order¶
The Quick Start tutorials make a request to the "Select" API.
Submit a request body with an AOI and optional date fields and query criteria. You can also submit a list of acquisition IDs with an optional AOI.
To learn how to select ARD imagery and view your results, see Select ARD Imagery to Order.
Before you submit a select request, read the Area of Interest (AOI) Examples and Guidelines.
4. Order ARD imagery¶
ARD can be ordered from the selection results or from a list of acquisition IDs. The Quickstart tutorials use a select ID to order.
To learn how to configure and place an order, see Ordering ARD Imagery.
You will specify the cloud platform location for the order delivery as part of the order request. We recommend using a new prefix with each order to avoid overwriting existing data. See Adding imagery to an existing prefix for more information.
5. Access your order's output files¶
ARD orders are delivered to your personal cloud storage location. It's important to understand the files and directory structure. An explanation of ARD output files and directory structure can be found at ARD Directory Structure.
Quickstart examples¶
Quickstart tutorials provide step-by-step instructions with working examples for selecting, ordering, and working with ARD imagery. Choose one of the following options: