Order Resource¶

Last updated: December 1, 2022

Order¶

/order

Order requests¶

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 cell_ids, 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.	`"cell_ids": ["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 Block Adjustment (BBA) is run on the order.	false
hd	Determines whether HD technology 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"

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"
    }],
    "intersects": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))",
    "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",
            "cell_ids": ["Z47-122220121320"]
        },
         {
            "id": "10500100259DFB00",
            "cell_ids": ["Z47-122220121320", "Z47-122220121321"]
        },
        {
            "id": "104001006895E400",
            "cell_ids": ["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": "POLYGON ((-106.8 35.1,-106.4 35.1,-106.4 35.4,-106.8 35.4,-106.8 35.1))",
        "bbox": null,
        "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`

Order Resource¶

Order¶

Order requests¶

Headers¶

Place an order¶

Request Body¶

Settings object¶

output_config object¶

Amazon S3 Cloud storage¶

Azure Blob Storage¶

Google Cloud storage¶

Dry Run for order validation (dry_run)¶

Notifications¶

Example: Order by select ID¶

Example: Order by acquisitions and an AOI¶

Example: Order by a list of acquisitions and cells¶

Example: Validate the order before submitting¶

Example request to validate order¶

Example Validation Order response¶

Example: Place an Order response¶

Get the status of an order¶

Example request¶

Response¶

Example status response¶

Response fields¶

Acquisition Details object¶

Order object¶

Order status¶

Acquisition status¶

List user's orders¶

Query parameters¶

Filter parameter¶

More documentation¶