Ordering ARD Imagery¶

Last updated: December 1, 2022

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",
        "cell_ids": ["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
hd	Determines whether `hd` 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
}

30 CM HD¶

Maxar ARD now includes an HD setting. HD upscales imagery with lower resolution to 30cm resolution. The hd field controls whether HD technology is run on your imagery order. By default, the value is "false".

To run HD on the imagery in your order:

Include the settings object with the hd field in your request.
Set the field to "hd": true.

Example:

"settings": {
  "hd": true
}

Ordering imagery that that is already at 30 cm resolution with the HD setting on will result in an this HD Error Message.

Ordering HD imagery within a restricted AOI will result in HD not running and the tile metadata properties object will update to reflect that result Tile Metadata.

If you are selecting imagery to order with HD technology, including "query":{ "pan_resolution_avg": { gte: 0.4 }} in your initial query will filter out acquisitions that do not meet the criteria for HD imagery.

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/

Creating a new prefix for an order (recommended)¶

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¶

The most common method for the delivery of ARD imagery is through Amazon S3 buckets. 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. If using the UI, you may also press the "view policy" button within the S3 bucket field to see an example policy.
- 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 also deliver imagery to 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.

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

To receive SNS notifications, you need an SNS topic with an access policy that allows ARD to publish notifications.

To learn how to set up an SNS topic, see the Amazon SNS Documentation.

Access policy¶

Your SNS topic must have an access policy that gives ARD publish access.

Edit your access policy configurations to include the ARD principal, and with the required "Publish" action. Below is an example of a functional Access Policy that can be copied and pasted directly into the JSON editor.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::334489843805:root"
      },
      "Action": "sns:Publish",
      "Resource": "*"
    }
  ]
}

The values in the JSON object for Effect, Principal, and Action should not be changed.

You can replace "*" with a resource or submit it as is.

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"
      }
  ]

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.

Ordering ARD Imagery¶

Selecting imagery to order¶

Constructing an order request¶

Choose imagery to order¶

Order by select ID¶

Order by a list of acquisitions with an AOI¶

Optional field for additional tracking data¶

Settings¶

Settings¶

Run Bundle Block Adjustment¶

30 CM HD¶

Specify the cloud platform and order delivery location¶

Including a prefix for order delivery¶

Creating a new prefix for an order (recommended)¶

Adding ordered files to an existing prefix¶

Amazon S3¶

Microsoft Azure and Google Cloud setup¶

Microsoft Azure Blob Storage¶

Google Cloud Storage¶

Validate your order before submitting (Dry Run)¶

Request Email or SNS notifications¶

Email notification request¶

Email notification example¶

Amazon Simple Notification Service (SNS) notifications¶

Access policy¶

Configuring SNS notifications in an order request¶

SNS notification examples¶

Order response¶

Example: Successful order response¶

Error Codes¶

Get the status of an order¶

Example: Get order status request¶

Example: Order status response¶

Example status response¶

List orders¶

Non-intersecting tiles and partial order fulfillment¶