Skip to content

Order Resource

Last updated: August 30, 2022


Order

/order
See also: Ordering Imagery User Guide

Order endpoints

http method path description
POST /order Place an order
GET /order/status/{order-id} Get the status of an order
GET /order List your orders

Headers

key value description
Authorization Bearer {{token}} Authentication method for ARD API requests.
Content-Type application/json Applies to POST, PATCH, PUT requests, which require a JSON body.

Place an order

POST /order

There are three types of "Place an Order" requests:

  • Order by select_id or query_id

  • Order by acquisitions and cells, with an optional AOI

  • Validate the order before submitting

Request Body

The following fields are used to construct an order request body.

field required description example
acquisitions required if no select ID is used. Submit an order using the id(s) of specific acquisitions. If using acquisitions, you cannot use select_id. "acquisitions": ["10300100B3841C00", "10300100AC700900"]
cells optional The unique identifier for the cell you want to order imagery from. The cell ID is the UTM zone and quadkey address of the grid cell. "cells": ["Z47-122220121320"]
select_id required if not ordering by acquisitions. Submit an order using the results of a select request by using the select id. If using select_id, you cannot use acquisitions. In the "select" response, this field is labeled 'id'. "id": "5710090499017518496"
bbox optional Submit a bounding box (bbox) to limit the area of ARD ordered. The intersects and bbox fields cannot be used in the same request. "bbox": [-106.8, 35.1, -106.4, 35.4]
intersects optional A polygon or multipolygon in WKT or GeoJSON geometry format. The intersects and bbox fields cannot be used in the same request. See example request.
metadata optional A place to input data you want to track for an order, such as a project name or project ID. This field accepts any value type. "metadata": {"project_id": "abdc-534-b4dc47"}
settings optional Use the Settings object to turn on BBA or exclude one or more masks from the order delivery. See "Settings object" below. See example request
output_config required Define the output configuration for the cloud storage platform where the order will be delivered. Amazon S3, Azure Blob Storage, and Google Cloud Storage are supported. See "output_config" table below.
dry_run optional Performs a validation check for an order request when the value is true. The response also provides estimated cost data for the order. "dry_run": true
notifications optional An array of notification outlets. Each outlet configuration must have a "type" field with a value of email or sns. If the type is sns, the configuration must include a topic_arn field. If the type is email, then the configuration must include an address field. "notifications": [{"type": "email","address": "[shea.barnes@myemail.com]"}

Settings object

The default values for these fields can be overridden by including them in the Settings object. Any fields not included in Settings will retain their default values.

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

Example:

"settings": {

    "bundle_adjust": true,
     "healthy_vegetation_mask": false,
     "water_mask": false
 },

output_config object

This table describes the fields in the output_config section of an order. The output configuration section determines where the order is delivered. Amazon S3, Azure Blob Storage, and Google Cloud Storage are supported.

field required description example
amazon_s3 required for s3 delivery. Configure order delivery to your Amazon S3 storage location. Requires bucket and prefix "amazon_s3":{"bucket": "my-ard-bucket","prefix": "denver-co"}
bucket required for s3 delivery. The destination S3 bucket for order delivery. "bucket": "my-ard-bucket"
prefix optional The prefix destination for delivery of ordered ARD tiles. If the prefix is not included, ordered data is delivered to the bucket. "prefix":"denver-co"
azure_blob_storage required for Azure Blob Storage deliveries Configure delivery to Microsoft Azure Blob Storage. "azure_blob_storage":
sas_url required if credentials_id is not used. The SAS URL that gives Maxar ARD permission to write to your Azure Blob Storage location. "sas_url": "https://storagesample.blob.core.windows.net/?..."
credentials_id required if Azure SAS URL is not used The credentials ID to use when looking up an SAS URL registered with your ARD account. Required if sas_url is absent. The administrator of your account can provide this location. "credentials_id": "our-shared-credentials"
container required for Azure Blob Storage delivery. The container to which ARD orders will be delivered. "container": "my-ard-container"
prefix required for Azure Blob Storage delivery. The prefix destination for order output files. The container and prefix combine to create the location the output files are saved to. "prefix": "example/prefix"
google_cloud_storage required for google cloud delivery. Configure delivery to Google Cloud Storage. "google_cloud_storage":
service_credentials optional The base64-encoded service credentials document to use when writing data to Google Cloud Storage; required if credentials_id is absent. "service_credentials": "... base64-encoded credentials doc ..."
credentials_id required if Azure SAS URL is not used The credentials ID to use when looking up an SAS URL registered with your ARD account. Required if sas_url is absent. The administrator of your account can provide this location. "credentials_id": "our-shared-credentials"
bucket required for Google Cloud Storage delivery. Destination bucket for ARD delivery. See output_config.google_cloud_storage.prefix example.
prefix required for Google Cloud Storage delivery. Prefix destination for output files. The bucket and prefix combine to create the path where the output files are saved. "prefix": "example/prefix"

Output configuration (output_config)

The "bucket" or "location" is a required field in the output configuration. The value should include the bucket name, with no forward or trailing slashes.

For example, if you are using Amazon S3 cloud storage, and your S3 bucket name is ard-demo-project, it should look like this in the request:

    "output_config": {
        "amazon_s3": {
            "bucket": "ard-demo-project"

Using a prefix is recommended, but not required. If a prefix is not included, the data is delivered to the root of the bucket. We also recommend using a new prefix for each delivery.

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/

This section shows output_config examples for setting up delivery to each of the cloud storage options.

Amazon S3 Cloud storage
    "output_config": {
        "amazon_s3": {
            "bucket": "example-bucket",
            "prefix": "example/prefix"
    }
}
Azure Blob Storage

Example: Azure Blob Storage using a credentials_id

{
"output_config": {
      "azure_blob_storage": {
        "credentials_id": "our-shared-credentials",
        "container": "my-ard-container",
        "prefix": "example/prefix"
      }
  }
}

Example: Azure Blob Storage using sas_url

{
  "output_config": {
    "azure_blob_storage": {
      "sas_url": "https://storagesample.blob.core.windows.net/?...",
      "container": "my-ard-container",
      "prefix": "example/prefix"
    }
  }
}
Google Cloud storage

{
    "output_config": {
        "google_cloud_storage": {
            "service_credentials": "... base64-encoded credentials string ...",
            "bucket": "my-ard-bucket",
            "prefix": "example/prefix"
        }
    }
}
See Google Cloud Storage setup

Dry Run for order validation (dry_run)

To validate your order and see usage estimates before submitting, include the clause

"dry_run": true
Notifications

Orders can be configured to send email or SNS notifications.

Email notifications:

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

SNS notifications:

"notifications": [
  {
        "type": "sns",
        "topic_arn": "valid-topic-arn"
    }
  ]  

Example: Order by select ID

{
    "select_id": "5519544966218982440",
    "output_config": {
        "amazon_s3": {
            "bucket": "example-bucket",
            "prefix": "example/prefix"
        },
        "metadata": {
            "project_name": "albuquerque"
        },
        "settings": {
            "bundle_adjust": true,
            "water_mask": false
        },
        "notifications": [{
            "type": "email",
            "address": "shea.barnes@myemail.com"
        }]
    }
}

Example: Order by acquisitions and an AOI

{
    "acquisitions": [{
        "id": "10403C0001FD6000"
    }],
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "output_config": {
        "azure_blob_storage": {
            "sas_url": "https://storagesample.blob.core.windows.net/?...",
            "container": "my-ard-container",
            "prefix": "example/prefix"
        },
    "metadata": {
        "project_id": "abdc-534-b4dc47"
        },
    "settings": {
        "bundle_adjust": true,
        "healthy_vegetation_mask": false,
        "water_mask": false
        },
    "notifications": [{
        "type": "email",
        "address": "useremail@myemail.com"
        }]
    }
}

Example: Order by a list of acquisitions and cells

{
     "acquisitions": [
        {
            "id": "10500100259DFB00",
            "cells": ["Z47-122220121320"]
        },
         {
            "id": "10500100259DFB00",
            "cells": ["Z47-122220121320", "Z47-122220121321"]
        },
        {
            "id": "104001006895E400",
            "cells": ["Z47-122220121320"]
        }
    ],
    "output_config": {
        "amazon_s3": {
            "bucket": "user-docsdemo",
            "prefix": "test-order-by-cell"
        }
    },
    "dry_run": true,
    "notifications": [{
        "type": "email",
        "address": "shea.barnes@myemail.com"
    }]
}

Example: Validate the order before submitting

To validate an order before sending it, add "dry_run":true to your order request. This will show whether your order passes validation checks. It will also show estimated usage.

Example request to validate order

{
  "acquisitions": ["10300100B3841C00","10300100AC700900"],
  "bbox": [-106.8, 35.1, -106.4, 35.4],
    "settings": {
        "bundle_adjust": true,
         "healthy_vegetation_mask": false,
         "water_mask": false
     },
   "output_config": {
        "amazon_s3": {
            "bucket": "ard-docs-bucket",
            "prefix":"denver-co"
        }
  },
  "dry_run": true,
  "notifications": [
        {
            "type": "email",
            "address": "shea.barnes@myemail.com"
        }
    ]
}

Example Validation Order response

Status: 202 Accepted

{
    "message": "Order dry-run validation successful.",
    "usage": {
        "area": {
            "fresh_imagery_sqkm": 0,
            "standard_imagery_sqkm": 414,
            "training_imagery_sqkm": 0,
            "total_imagery_sqkm": 414,
            "estimate": true
        },
        "cost": {
            "fresh_imagery_cost": 0,
            "standard_imagery_cost": 5,
            "training_imagery_cost": 0,
            "total_imagery_cost": 5,
            "estimate": true
        },
        "limits": {
            "limit_sqkm": -1,
            "annual_subscription_fee_limit": 100000.00,
            "fresh_imagery_fee_limit": 0,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1
        },
        "available": {
            "available_sqkm": -1,
            "total_imagery_balance": -1,
            "fresh_imagery_balance": -1,
            "standard_imagery_balance": -1,
            "training_imagery_balance": -1
        },
        "usage_as_of": "2021-07-23T20:16:24Z"
    }
}
Example: Place an Order response

This link requires ARD authentication.

Status: 202 Accepted

{
    "id": "7073524246258252",
    "links": {
        "status": "https://ard.maxar.com/api/v1/order/status/7073524246258252"
    }
}
Field Description Example value
id the ID assigned to the order. Use this ID number to make a "get order status" request. string: ex. 7073524246258252
links.status the URL to make a "get order status" request. Authentication is required. https://ard.maxar.com/api/v1/order/status/7073524246258252

Get the status of an order

GET /order/status/{order_id}

Retrieves the status-related fields for a given order.

Example request

GET /order/status/7073524246258252

Response

Example status response

Status: 200 OK

{
    "id": "7073524246258252",
    "status": "SUCCEEDED",
    "status_message": "Order complete",
    "acquisition_details": [
        {
            "status_message": "ARD for acquisition is complete",
            "id": "03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv",
            "status": "SUCCEEDED"
        }
    ],
    "order": {
        "id": "7073524246258252",
        "account": "995568860438844188",
        "user_id": "85914d9c-d5d8-4903-a89d-455",
        "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": 0.02,
                "total_imagery_cost": 0.02,
                "estimate": false
            }
        },
        "duration": "0:04:27.839000",
        "acquisitions": [
            {
                "cell_ids": [],
                "id": "03cf5011-7fd0-49ab-8bcf-36d7e2a1075f-inv"
            }
        ],
        "intersects": null,
        "bbox": [-106.8, 35.1, -106.4, 35.4],
        "status": "SUCCEEDED",
        "status_message": "Order complete",
        "settings": {
            "bundle_adjust": false,
            "water_mask": true,
            "cloud_mask": true,
            "ms_saturation_mask": true,
            "healthy_vegetation_mask": true,
            "terrain_shadow_mask": true,
            "pan_flare_mask": true
        },
        "output_config": {
            "amazon_s3": {
                "bucket": "user-docs-demo",
                "prefix": "example-prefix"
            }
        },
        "notifications": [
            {
                "type": "email",
                "address": "shea.barnes@myemail.com"
            }
        ],
        "date_created": "2022-03-30T16:34:01Z",
        "date_modified": "2022-03-30T16:38:31Z"
    },
    "response_timestamp": "2022-03-30T17:32:56Z"
}

Response fields

The fields displayed in the response to a status request.

field description
id The ID assigned to the order.
status The status of the order.
status_message A status message that provides more detail about the order and its progress.
acquisition_details An object that provides a status and a status message for each acquisition in the order.
order An object that provides the details about the order.
response_timestamp The timestamp of the response.

Acquisition Details object

The fields displayed in an acquisition_details object. Each acquisition is a separate object.

field description
status_message Provides more detail about the status of an acquisition in an order.
id The unique identifier for an image acquisition in an order.
status The order status for the acquisition.

Example acquisition_details object:

        {
            "status_message": "Generating ARD tiles",
            "id": "10300100CF97E500",
            "status": "PROCESSING"
        }

Order object

field description
id The unique identifier assigned to the order.
account The unique identifier for the account that placed the order.
user_id The unique identifier for the user that placed the order.
usage The sqkm usage and costs incurred as a result of this order. These numbers are estimates until the order is complete.
duration The amount of time between when the order was placed and when it was delivered and marked as "SUCCEEDED: Order complete".
acquisitions The acquisitions and cell IDs in the order request.
intersects The coordinates of the AOI polygon or multipolygon.
bbox The bounding box coordinates in [minx, miny, maxx, maxy] format.
status The status for the order.
status_message Provides more detail about the status of an acquisition in an order.
select_id If an ID from a "select" or "cell metadata" API request was used to place the order, it will be displayed here.
settings Order processes and files are listed in the "settings" object with a value of "true" or "false". For processes, "true" indicates the process will be run. For files, "true" indicates the file will be delivered. The values shown in the example above are default values.
output_config The cloud platform, bucket or container, and prefix where the order has been or will be delivered.
notifications The method selected for order notifications. This can be email, SNS, or both.
date_created The date and time the order request was received.
date_modified This date and time will match the date_created field.

If a value for a field was not supplied in the order request, it will show a default value or a value of "null".

Order status

Status codes and messages that apply to an order.

order status status message description
RUNNING "Ordering imagery" The imagery used to generate ARD is being ordered.
RUNNING "Generating tiles" The ordered ARD tiles are being generated.
SUCCEEDED "Order complete" All files for an order delivery have been delivered to the location specified in the output configuration.
FAILED "Your order encountered a problem; please contact ARD support for more information" The order failed and no imagery or metadata files were delivered.
CANCELED "Your order encountered a problem; please contact ARD support for more information" The order failed and no imagery or metadata files were delivered.

Acquisition status

Status codes and messages that apply to an acquisition that is part of an order.

acquisition status status message description
ORDERING "Ordering 1B" The acquisition is being ordered. "1B" indicates the Maxar product level of the imagery that ARD tiles are generated from.
PROCESSING "Generating ARD tiles" ARD tiles are being generated from the acquisition.
DELIVERING "Delivering ARD tiles to customer" The ordered ARD tiles have been generated and are being delivered to the customer's cloud platform location.
SUCCEEDED "ARD for acquisition is complete" ARD tiles for the acquisition have been delivered to the customer's cloud platform location.
NO_INTERSECTING_TILES "Requested cell_ids do not intersect the acquisition and/or aoi" One or more tiles from the acquisition did not intersect with the AOI. When this happens, any tiles that do intersect the AOI are delivered, but the non-intersecting tiles are not.
FAILED "1B order failed" The acquisition could not be ordered from the archive so ARD tiles cannot be generated. When an acquisition fails the ordering process, the entire order fails.
FAILED "ARD tile delivery failed" The generated ARD tiles could not be delivered to the customer's cloud platform location.
FAILED "Acquisition aborted due to another acquisition failure" The tiles for this acquisition will not be delivered because another acquisition in the order failed. When one acquisition fails, the entire order fails and will not be delivered.

List user's orders

Retrieves a page listing of orders for the user who makes the request. Query parameters can be passed to limit or refine the results. Orders are sorted from newest to oldest.

GET /order

Example:

GET https://ard.maxar.com/api/v1/order

Role: User

Query parameters

All query parameters are optional. If no parameters are used, a default of 10 orders will be returned, starting from the newest order.

query param description example
end_date Indicates the last date for which orders should be displayed, based on order creation date. The date must be in ISO-8601 format YYYY-MM-DD. end_date=2017-01-01
ending_before Page backward from the specified orderID. ending_before=5575483352480018730
filter Filter orders by a specific value in one of the order metadata fields. See Filter options below. filter=date_created:2021-06-08
limit The number of orders to return in the response. This defaults to 10. limit=5
start_date Indicates the earliest order to display, based on order creation date. Orders are returned from that date to the date the list orders request is made. The date must be in ISO-8601 format YYYY-MM-DD. start_date=2017-01-01
starting_after Page forward from a specified orderID. starting_after=5575303766309754274
sort indicates sort order, desc (default) for descending order (newest first) and asc for ascending order (oldest first) sort=asc
Filter parameter

Use the filter parameter to filter by any queryable field in the order's metadata.

GET order?filter=status:RUNNING
To filter for a nested field, separate with a period ..

Example: output_config.google_cloud_storage.bucket:my-ard-bucket

To filter by multiple fields at once, add two "filter" clauses, separated by an ampersand &.

Example: GET https://ard.maxar.com/api/v1/order?filter=date_created:2021-06-08&filter=bundle_adjust:true

The following fields from an Order's metadata are queryable using the "filter" query parameter:

field description example
date_created Filter for all orders created on a specified date. filter=date_created:2021-06-08
metadata Filter for a name/value pair in the metadata field. metadata.project_code:abq-cars
output_config Filter for orders with a specific value set for a parameter in the output_config section. filter=output_config.google_cloud_storage.bucket:my-ard-bucket
status Filter for orders by current status. filter=status:running

More documentation

Ordering ARD Imagery Guide

Amazon S3 Bucket Policy Configuration

Bundle Block Adjustment (BBA) Validation

Area of Interest Examples and Guidelines

Usage Guide

Back to top