Skip to content

Ordering ARD Imagery

Last updated: July 12, 2022


See also: Order API reference

Selecting imagery to order

To order ARD imagery, we recommend making a "select" request first. Then use the ID from the response to order the imagery in your results. You can visualize the imagery results, download files that describe the selection, and view the estimated usage that would be incurred if the imagery is ordered. You can refine a select request until you're satisfied with the results. A select request does not incur usage costs.

See Select ARD Imagery to Order.

ARD can also be ordered by submitting a list of acquisition IDs. You can include an AOI in the request.

Constructing an order request

This is an example Order request body. Each part will be explained below.

{
"acquisitions": [
    {
        "id": "10300100B2B49700",
        "cells": ["Z13-031133320203"]
    }
],
"bbox": [-106.8, 35.1, -106.4, 35.4],
"metadata": {
  "project_id": "abdc-534-b4dc47"
  },
"settings": {
    "bundle_adjust": true,
    "pan_flare_mask": false
},
"output_config": {
    "amazon_s3": {
        "bucket": "user-docs-demo",
        "prefix": "abq_04-2022"
    }
},
"dry_run": true,
"notifications": [{
    "type": "email",
    "address": "shea.barnes@myemail.com"
}]

}

IMPORTANT: "Dry Run" is used to validate that an order will succeed without submitting it. To place an order, remove the "dry_run": true clause or set the value to false.

Choose imagery to order

The order request body includes either the "select_id" or a list of acquisitions to order. An AOI may be supplied with the acquisitions list. The select_id is the value from the "id" field at the top of the select API response.

Order by select ID

Use the Select API to select imagery. Then use the select ID from the response to place an order.

Example: select_id clause

  "select_id": "5519544966218982440"

Order by a list of acquisitions with an AOI

Acquisition ID is also referred to as a catalog ID in some Maxar systems. List the acquisitions you want to order and constrain it by an AOI. If the acquisitions don't intersect with the provided AOI, the order will return an error.

Example: List of acquisitions with a bounding box clause

  "acquisitions": ["10300100B3841C00", "10300100AB101A00", "10300100A67D3100", "10300100AC700900"],
  "bbox": [-106.8, 35.1, -106.4, 35.4]

Example: List of acquisitions with a WKT-formatted polygon AOI

  "acquisitions": ["10300100B3841C00", "10300100AB101A00", "10300100A67D3100", "10300100AC700900"],
    "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))"

Optional field for additional tracking data

The "metadata" field is an optional field that can be used for tracking additional information with an order. For example, you may want to associate a project name or project ID with an order.

Example:

"metadata": {
        "project_code": "abq-cars"
    }

You can query for orders based on a value in the metadata field, using the "filter" parameter on the "list orders" API request. This field is also returned in the response of a "GET order status" request.

Example parameter on a GET orders request:

https://ard.maxar.com/api/v1/order?filter=metadata.project_code:abq-cars

Settings

The Settings object lets you:

  • run Bundle Block Adjustment (BBA) on ordered imagery. BBA is off (false) by default.

  • specify which masks to include in your delivery. All masks are included (true) by default.

The Settings object is optional. If it is not included, the default values for each setting will be applied.

Settings

These are the fields that can be updated in the settings object.

setting description default value
bundle_adjust Determines whether bundle_adjust is run on the order. false
cloud_mask Determines whether the cloud/cloud shadows raster and vector masks are delivered in the order. true
healthy_vegetation_mask Determines whether the healthy vegetation raster and vector masks are delivered in the order. true
ms_saturation_mask Determines whether the multispectral saturation raster and vector masks are delivered in the order. true
pan_flare_mask Determines whether the panchromatic flare raster and vector masks are delivered in the order. true
terrain_shadow_mask Determines whether the terrain shadow raster and vector masks are delivered in the order. true
water_mask Determines whether the water raster and vector masks are delivered in the order. true

Run Bundle Block Adjustment

The bundle_adjust field controls whether BBA is run on your imagery order. By default, the value is "false".

To run BBA on the imagery in your order:

  • Include the settings object with the bundle_adjust field in your order request.

  • Set the field to "bundle_adjust": true

Example:

"settings": {
       "bundle_adjust": true
   }

Specify the cloud platform and order delivery location

Maxar ARD supports order delivery to Amazon S3, Microsoft Azure Blob storage, and Google cloud platforms. These are specified in the output configuration section of an order. See Orders API reference for documentation and examples.

Use the output_config section of the order request to specify the cloud platform, the bucket or container name, and the prefix. The order outputs will be delivered to the location you specify.

Including a prefix for order delivery

In the output configuration section of an order, you can specify a bucket or container (depending on the cloud storage platform) and a prefix. This is similar to creating a directory and subdirectory.

The ordered data is delivered to the bucket or container/prefix location specified in the order request body. Using a prefix is optional, but recommended. If no prefix name is submitted in the order request, the output files will be delivered to the bucket's root directory.

We recommend that you create a new prefix for each order. This will keep your data organized and prevent the possibility of data being unintentionally overwritten. For example, if orders that use the same acquisition IDs in the same quadkeys, but with a different AOI are sent to the same prefix, the original data could be overwritten.

All files for an order are delivered to a single prefix.

The prefix can be formatted in any of the following ways:

  • a string of text. For example: my-prefix-location

  • multiple prefix levels are allowed, and must be separated by a forward slash /. For example, my-prefix-location/level2/level3.

  • starting or trailing forward slashes can be included in a prefix name, but are ignored.

For example, any of these will work:

my-prefix-location
/my-prefix-location/
/my-prefix-location
my-prefix-location/
/my-prefix-location/level2
/my-prefix-location/level2/

A new prefix is created by adding a new name to the “prefix” field in the order.

Example:

    "prefix": "example-prefix"

Find a naming convention that works best for you. You’ll need to remember the prefix to find your order output files once they’re delivered to your cloud storage bucket or container.

Adding ordered files to an existing prefix

Writing data to an existing prefix comes with the risk of inadvertently replacing existing images with duplicates covering the same area but having different processing options.

For example, if a new order includes acquisitions (image strips) that have already been delivered to the prefix, and anything about those acquisitions is different from the original files (i.e., the AOI has changed, or BBA processing was applied and pixels were adjusted) the existing data will be overwritten.

You can safely add to an existing collection of images in one prefix by adding from date ranges that do not overlap.

Amazon S3

Delivery to an Amazon S3 bucket and prefix location requires the following:

  • An S3 bucket policy must be applied. This policy gives Maxar ARD "write" permission to the bucket. Maxar's access to your bucket is limited to writing objects to your bucket. We don't read or edit data stored in your bucket. See Set up an Amazon S3 bucket policy for setup instructions.

The Max-ARD SDK has tools to create and configure an S3 bucket. https://ard.maxar.com/docs/sdk/sdk-quickstart/sdk-quickstart/#step-3-create-an-s3-bucket-policy-and-give-maxar-write-access

  • The output_config section of an order request must specify the Amazon S3 bucket and prefix where the output files should be delivered.

Example:

{
  "output_config": {
    "amazon_s3": {
      "bucket": "user-docs-demo",
      "prefix": "example-prefix"
    }
  }
}

Microsoft Azure and Google Cloud setup

The ARD ordering system can deliver imagery to Amazon S3, Azure Blob Storage, or Google Cloud Storage. This can be done using one of the following methods:

The administrator for your ARD account registers a set of long-lived Azure or Google cloud credentials with the ARD credentials service and assigns a credentials ID. The credentials ID is submitted as part of the order request. This is the recommended method.

See Google Cloud Delivery Setup.

See Credentials Service for more information.

Example:

{
    "output_config": {
        "google_cloud_storage": {
            "credentials_id": "our-shared-credentials",
            "bucket": "user-docs-demo",
            "prefix": "example-prefix"
        }
    }
}

The credentials are submitted as part of the order request. See the sections below for examples of Azure Blob Storage and Google Cloud Storage credentials submissions.

Microsoft Azure Blob Storage

A Microsoft Azure Blob Storage SAS URL can be submitted in the order's output configuration without being registered.

Example: Azure Blob Storage using sas_url

{
  "output_config": {
     "azure_blob_storage": {
       "sas_url": "https://storagesample.blob.core.windows.net/?sv=2020-02-10&ss=b&srt=o&sp=wx&se=2021-03-30T23:38:50Z&st=2021-03-23T15:38:50Z&spr=https&sig=...",
       "container": "user-docs-demo",
       "prefix": "example-prefix"
     }
  }
}

Google Cloud Storage

The ARD Ordering API requires a base64 encoded credentials string for Google cloud storage access.

Example:

{
  "output_config": {
     "google_cloud_storage": {
       "service_credentials": "... base64-encoded credentials doc ...",
       "bucket": "user-docs-demo",
       "prefix": "example-prefix"
     }
   }
}

Validate your order before submitting (Dry Run)

You can validate your order before submitting it. Validating an order verifies that the ARD system can write files to your S3 bucket and prefix, and checks for common errors. It writes a test file to your s3 location, but does not complete the order.

To validate your order, add this to your request:

"dry_run": true

See the full example above for placement in the request body. Once you've verified that your order will succeed, remove "dry_run": true from the request and submit the order.

If validation is successful, the response code will be a 202 Accepted, with this message body:

"message": "Order dry-run validation successful."
The response also includes estimated usage for the order. See Order API reference to view an example response to a valid order request.

Request Email or SNS notifications

The final piece of the order request is the "notifications" section. The request must include either email or sns notifications. Both can be requested.

Email notification request

"notifications": [
      {
          "type": "email",
          "address": "shea.barnes@myemail.com"
      }
  ]

Email notification example

email notification

Amazon Simple Notification Service (SNS) notifications

If you have an SNS topic set up, you can request SNS notifications for order status.

Prequisite: SNS Topic set up

For helping setting up an SNS topic, see the Amazon SNS Documentation

When setting up your SNS topic, add the following account to your access policy:

arn:aws:iam::334489843805:root

This is what it would look like in the JSON object

"Principal": {
        "AWS": [
          "arn:aws:iam::334489843805:root"
        ]
      }
Configuring SNS notifications in an order request

The notifications object requires the following:

  • the notification type must be "sns" .

  • a topic Amazon Resource Name (ARN) is required. The naming convention for a topic ARN is arn:aws:sns:[region]:[aws account id]:[topic].

"notifications": [
      {
          "type": "sns",
          "topic_arn": "arn:aws:sns:us-east-1:1234567890987:my-topic"
      }
  ]

SNS notification examples

This is a successful order notification.

{
    "id": "1244152800623822642",
    "status": "SUCCEEDED",
    "status_message": "Order complete",
    "acquisition_details": [
        {
            "status_message": "ARD for acquisition is complete",
            "id": "03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv",
            "status": "SUCCEEDED"
        }
    ],
    "usage": {
        "area": {
            "fresh_imagery_sqkm": 0,
            "standard_imagery_sqkm": 0,
            "training_imagery_sqkm": 2.1,
            "total_imagery_sqkm": 2.1,
            "estimate": false
        },
        "cost": {
            "fresh_imagery_cost": 0,
            "standard_imagery_cost": 0,
            "training_imagery_cost": 6.3,
            "total_imagery_cost": 6.3,
            "estimate": false
        }
    },
    "metadata": {
          "project_code": "abq-cars"
      },
    "output_config": {
        "amazon_s3": {
            "bucket": "user-docs-demo",
            "prefix": "abq-demo"
        }
    },
    "duration": "8:17:07.900000",
    "order_details_url": "https://ard.maxar.com/api/v1/order/status/1244152800623822642"
}

This is a failed order notification. In this example, the order failed because no tiles in the order intersected the AOI. The estimated usage data is included in the response, but you will not be charged for a failed order.

{
  "id": "1244844015424935519",
  "status": "FAILED",
    "status_message": "Your order encountered a problem; please contact ARD support for more information",
    "acquisition_details": [
        {
            "status_message": "Requested cell_ids do not intersect the acquisition and/or aoi",
            "id": "103001000733D300",
            "status": "NO_INTERSECTING_TILES"
        }
    ],
    "usage": {
        "area": {
            "fresh_imagery_sqkm": 0,
            "standard_imagery_sqkm": 0,
            "training_imagery_sqkm": 2.1,
            "total_imagery_sqkm": 2.1,
            "estimate": true
        },
        "cost": {
            "fresh_imagery_cost": 0,
            "standard_imagery_cost": 0,
            "training_imagery_cost": 6.3,
            "total_imagery_cost": 6.3,
            "estimate": true
        }
    },
    "metadata": {
          "project_code": "abq-cars"
      },
    "output_config": {
        "amazon_s3": {
            "bucket": "user-docs-demo",
            "prefix": "abq-demo"
        }
    },
    "duration": "null",
    "order_details_url": "https://ard.maxar.com/api/v1/order/status/1244844015424935519"
}

Order response

When an order request is successfully submitted, it will return a 202 OK response. An http 202 request indicates the request has been accepted.

Example: Successful order response

{
    "id": "7073524246258252",
    "links": {
        "status": "https://ard.maxar.com/api/v1/order/7073524246258252"
    }
}
  • id: the ID assigned to the order. Use this ID number to make a "get order status" request.

  • links: status: use the URL provided in the "status" field to make a "get order status" request.

Error Codes

If invalid JSON is sent (required fields missing or invalid types for fields), a 400 Bad Request with a human-readable message will be returned.

If the system encountered an error storing the order definition, a 500 Internal Server Error will be returned.

For more information, see Error Codes and Conditions

Get the status of an order

To see the status of an order, send a GET request with the order ID.

Example: Get order status request

GET /order/status/:order_id
GET /order/status/7073524246258252

Example: Order status response

The response to an order status request provides a status update and includes the order request body in the response. This example shows the response to an order that was placed using the "select ID" as the input. For other response examples, see API Reference: Get order status.

Example status response

Status: 200 OK

{
  "id": "1244308061171029536",
  "status": "SUCCEEDED",
  "status_message": "Order complete",
  "acquisition_details": [
      {
          "status_message": "ARD for acquisition is complete",
          "id": "10300100B2B49700",
          "status": "SUCCEEDED"
      }
  ],
  "order": {
      "id": "1244308061171029536",
      "account": "985891500803692077",
      "user_id": "967f33a5-1d80-4a74-9334",
      "usage": {
          "area": {
              "fresh_imagery_sqkm": 0,
              "standard_imagery_sqkm": 25,
              "training_imagery_sqkm": 0,
              "total_imagery_sqkm": 25,
              "estimate": false
          },
          "cost": {
              "fresh_imagery_cost": 0,
              "standard_imagery_cost": 0.25,
              "training_imagery_cost": 0,
              "total_imagery_cost": 0.25,
              "estimate": false
          }
      },
      "duration": "9:14:29.601000",
      "acquisitions": [
          {
              "cell_ids": [
                  "Z13-031133320203"
              ],
              "id": "10300100B2B49700"
          }
      ],
      "intersects": null,
      "bbox": null,
      "status": "SUCCEEDED",
      "status_message": "Order complete",
      "select_id": null,
      "bundle_adjust": null,
      "metadata": {
          "project_id": "abq-cars"
      },
      "settings": {
          "bundle_adjust": true,
          "water_mask": false,
          "cloud_mask": true,
          "data_mask": true,
          "ms_saturation_mask": true,
          "healthy_vegetation_mask": false,
          "terrain_shadow_mask": true,
          "pan_flare_mask": true
      },
      "output_config": {
          "amazon_s3": {
              "bucket": "user-docs-demo",
              "prefix": "doc-example"
          }
      },
      "notifications": [
          {
              "type": "email",
              "address": "shea.barnes@myemail.com"
          }
      ],
      "date_created": "2022-06-15T18:59:00Z",
      "date_modified": "2022-06-16T04:13:35Z"
  },
  "response_timestamp": "2022-06-16T14:42:06Z"
}

See Order API Reference for a complete set of order status response examples.

List orders

Admins can make a request to list orders for the account. This request is part of the "Account" endpoint. See List orders for an account.

Users can list their own orders. This request is part of the "Order" endpoint. See List User's Orders

Non-intersecting tiles and partial order fulfillment

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 file is named {orderID}_non_intersecting_tiles_report.json and is located in the order_collections subdirectory of the ARD order delivery location.

If none of the tiles in an order intersect the AOI, the order will fail.

Back to top