Skip to content

Tasking

Last updated: December 1, 2022

Overview

The ARD Tasking API lets you task one or more Maxar satellites to collect imagery within your Area of Interest (AOI) and specified time frame. The resulting images are ordered as Analysis-Ready Data (ARD) and delivered to your cloud storage location. ARD Tasking is a subscription product and credits must be purchased up front.

The following steps take place to fulfill a tasking request:

  1. Customer makes a request to the Tasking API.

  2. The request is sent to the Maxar satellite tasking platform. It also generates an ARD monitor that watches for newly collected imagery.

  3. Collected images are automatically ordered as ARD, and an auto-order notification is sent.

  4. The order is delivered to your cloud storage location, and an order status notification is sent.

Collection for a tasking request continues until all cells that intersect the AOI have been covered or the collection end date has passed.

Place a Tasking request

A tasking request consists of the following components:

  • an AOI
  • a collection date range
  • optional query parameters
  • the order configuration that will be used to process and deliver collected imagery as ARD

Validate your request before submitting

When you submit a tasking request, the cost of your tasking request is immediately deducted from your account balance as opposed to a monitor where you are given the option to purchase imagery as they appear. You can validate your tasking request and check the cost of the request before you submit it. This is called a "dry run". This checks your request against validation rules, and it returns usage data in the response.

To submit a dry run tasking request, include "dry_run": true, in the request body as a top-level field. This field is included in the example below. To submit your request, update the dry_run value to false, or remove the field from the request. The default value is false.

Example request:

{
    "name": "albuquerque",
  "description": "albuquerque car counting project",
    "date": "2023-05-24/2023-06-24",
    "bbox": [-106.8, 35.1, -106.4, 35.4],
    "query": {
        "aoi:cloud_free_percentage": {
            "gte": 75.0
        },
        "view:off_nadir": {
            "lte": 20
        },
        "view:sun_elevation": {
            "gte": 25
        },
        "platform": {
            "in": ["worldview-02", "geoeye-01"]
        }
    },
  "dry_run": true,
    "order_config": {
        "output_config": {
            "amazon_s3": {
                "bucket": "my_bucket_name",
                "prefix": "my_prefix_name"
            }
        },
        "metadata": {
            "project_id": "project12345"
        },
        "settings": {
            "bundle_adjust": true,
            "healthy_vegetation_mask": false,
            "water_mask": false
        },
        "notifications": [{
            "type": "email",
            "address": "shea.barnes@myemail.com"
        }]
    }
}

Request body parameters

field name required description allowed values default
date required The value must be a date range in ISO-8601 format. Use a / to separate two date strings, e.g. “2023-10-25/2023-12-01”; for open-ended ranges use ..; for example: "2019-10-25/.." start date must be 1 day after submission; end date cannot be earlier than start date. default start date min is submission date + 1 day; default end date is the account's contract end date.
intersects Either the intersects or bbox field must be included. The AOI to collect imagery from in geojson geometry or WKT format. min = 25 sq kms, max = 10000 sq kms, min width = 250 meters. no default
bbox Either the intersects or bbox field must be included. The AOI to collect imagery from in [minx, miny, maxx, maxy] format. min = 25 sq kms, max = 10000 sq kms, min width = 250 meters. no default
query object optional The query parameters for the tasking collection. See query fields table below. each query field has a default value.
order config object required The order details for placing an order when collected images are available. see order details section below. n/a

Note: A request cannot include an AOI in both the intersects and the bbox field.

Query parameters

A tasking request accepts the following parameters in the "query" object. If no value is submitted for a parameter, the default value will apply.

parameter description allowed values allowed operators default example
aoi:cloud_free_percentage The percentage of the AOI that must be free of clouds. 1-100 gte 50 "aoi:cloud_free_percentage": {"gte": 75.0}
view:off_nadir The angle from the sensor between nadir (straight down) and the scene center, measured in degrees (0-90). (Note: for tiles, this is the average off-nadir angle of the full image strip.) 0 - 30 lte 30 "view:off_nadir": {"lte": 20}
view:sun_elevation The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). 5-90 gte 15 "view:sun_elevation": {"gte": 25}
platform One or more Maxar satellites to task for imagery collection. worldview-01, worldview-02, worldview-03, geoeye-01 eq, contains, in, not-contains worldview-02, worldview-03, geoeye-01 "platform": {"in": ["worldview-02", "geoeye-01"]}

Note: Nighttime imagery cannot be ordered as ARD. Nighttime imagery has a sun elevation of 0-5 degrees.

Operators

The ARD Tasking API request is translated and sent to Maxar's tasking platform. This means the query operators that can be used for each parameter are limited to what is listed in the "allowed operators" column in the table above.

Operator definitions

gte: greater than or equal to

lte: less than or equal to

eq: the results must equal the stated value

in: match any value in the group

contains: The filter value is in the field value

not contains: The filter value is not in the field value.

Order config

Images collected to meet a tasking request are automatically ordered and delivered to your cloud storage location. The order_config object must be included in the tasking request.

The order_config object includes the following fields:

object required description
output_config required Specify the cloud services provider and the storage location for your order delivery. Amazon S3, Google Cloud Storage, and Azure Blob Storage are supported.
notifications required Set up order status email notifications, sns notifications, or both.
metadata optional Additional data user specifies for the order. For example, you may want to associate an order with a project name or describe the area of interest for the order.
settings optional Add optional settings to change the processing of your order, such as running Bundle Block Adjustment (BBA) and turning off delivery of specified masks.

These objects are explained in detail in the ARD Ordering Guide.

Tasking API response

Dry Run validation response

This example shows the response to a request with "dry_run": true. The tasking_imagery_cost will be charged to the account's usage when the tasking request is submitted.

{
    "data": {
        "message": "Tasking dry-run validation successful.",
        "usage": {
            "area": {
                "tasking_imagery_sqkm": 220.0
            },
            "cost": {
                "tasking_imagery_cost": 7700.0
            },
            "limits": {
                "tasking_imagery_fee_limit": 10000.0
            },
            "available": {
                "tasking_imagery_balance": 2300.00
            },
            "usage_as_of": "2022-12-02T20:12:25Z"
        }
    },
    "links": {
        "request": "https://api.ard.maxar.com/tasking"
    },
    "request_timestamp": "2022-12-02T20:12:24Z",
    "response_timestamp": "2022-12-02T20:12:25Z",
    "request_duration": 1.0
}

This is an example response to a Tasking API request:

  {
    "data": {
        "id": "60609597630904043XX"
    },
    "links": {
        "monitor": "https://ard.maxar.com/api/v1/monitor/config/555555599999999",
        "request": "https://api.ard.maxar.maxar.com/tasking-tasking-usage"
    },
    "request_timestamp": "2022-11-23T17:45:02Z",
    "response_timestamp": "2022-11-23T17:45:13Z",
    "request_duration": 11.0
  }

This table explains each element of the response:

object field description
data id the unique identifier for the tasking request, also referred to in documentation as the "tasking id".
links monitor A link to the monitor generated by the tasking request. The monitor details show the fulfillment status for the tasking request.
links request The URL used to make the tasking request.
request_timestamp The date and time the request was submitted.
response_timestamp The time the response was returned.
request_duration The time in seconds between when the request was submitted and the response was returned.

We recommend keeping a copy of the Tasking ID and Monitor ID generated by your tasking request. The Tasking ID and the Monitor ID will appear in the "Order" details when collected images are automatically ordered. You'll use the Monitor ID to track fulfillment of your tasking request. See Checking the Fulfillment of a Tasking request.

Monitor for collected imagery

When a tasking request is submitted, it creates an ARD monitor that watches for newly-collected matching imagery. The monitor watches for imagery that:

  • matches the query parameters in the tasking request
  • fills in at least one cell that intersects the AOI

A monitor created from a tasking request is a "single match" monitor type. A single match monitor watches for new acquisitions that fill in the cells of the AOI. Once the AOI is filled in, the monitor will stop looking for matches. A monitor generated from a tasking request will have the tasking_id in the response.

See the Monitoring Guide for more information on single-match monitors.

You may view additional details about your tasking request by using that same tasking_id in a GET Tasking Details request. See the Tasking Guide for more details.

Automatic ordering

When a tasking monitor finds a new matching acquisition, it is automatically ordered, based on the order configuration that was defined as part of the Tasking request. The parts of the acquisition that intersect with the AOI are delivered as an ARD order delivery. You'll receive a notification when an image is automatically ordered for you.

When the tasking monitor finds a match a successfully places an order for it, the following message is sent:

Example email:

From: ard-support@maxar.com <ard-support@maxar.com>
Sent: Thursday, December 1, 2022 23:46
To: Barnes, Shea <shea.barnes@myemail.com>
Subject: Your Maxar ARD monitor auto-order succeeded

Your ARD Monitor found a match and is being automatically ordered.

Order ID: 606709059372831nnnn
Acquisition ID: 1050010030548800
Monitor: albuquerque(555555599999999)
Description: albuquerque car counting project

Questions? Contact ARD Support.

For details about the order, visit the following link (requires authentication):
Order 606709059372831nnnn

Visit these links to find details about the new acquisition. All links require authentication.
Q6067090585028653448 Details
Q6067090585028653448 GeoJSON
Q6067090585028653448 STAC
Q6067090585028653448 acquisition listing

For details about the matching monitor, visit the following link (requires authentication):
Monitor 555555599999999
Example sns notification:

{"monitor_id": "555555599999999 ", "monitor_name": “albuquerque”, "monitor_description": "albuquerque car counting project , "acquisition_id": "1050010030548800", "query_id": "Q6067090585028653448", "links": {"details": "https://ard.maxar.com/api/v1/metadata/query/Q6067090585028653448", "geojson": "https://ard.maxar.com/api/v1/metadata/query/Q6067090585028653448/results?format=geojson", "stac": "https://ard.maxar.com/api/v1/metadata/query/Q6067090585028653448/results?format=stac", "acquisitions": "https://ard.maxar.com/api/v1/metadata/query/Q6067090585028653448/results?format=order", "monitor": "https://ard.maxar.com/api/v1/monitor/config/555555599999999", "order": "https://ard.maxar.com/api/v1/order/status/06709059372831nnnn"}, "order_id": "606709059372831nnnn”}

Example notification when the auto-order cannot be placed:

subject: Your Maxar ARD monitor auto-order failed

Your ARD Monitor found a match, but it was unable to automatically order it.

Acquisition ID: 1040010058664C00
Monitor: albuquerque (555555599999999)
Description: albuquerque car counting project

Auto-order failed with error message:
[error message displays here]

You can retry the order by using this query ID in the "select_id" field of an order: Q6061602833847293088.
See the ARD Ordering Guide for more information.

Questions? Contact ARD Support.

Visit these links to find details about the new acquisition. All links require authentication.
Q6061602833847293088 Details
Q6061602833847293088 GeoJSON
Q6061602833847293088 STAC
Q6061602833847293088 acquisition listing

For details about the matching monitor, visit the following link (requires authentication):
Monitor 6060960822285970792

Check the fulfillment status of a Tasking request

The fulfillment status of a tasking request is tracked in the tasking Monitor. The Monitor keeps track of percentage of coverage for the following:

  • remaining area: the coordinates for the parts of the AOI still to be collected

  • remaining cell ids: the ids for the cells still to be collected

  • percent remaining: the percentage of the AOI still to be fulfilled for the tasking request

See the Monitor Guide to learn more about the details of a Monitor.

You may also view details surrounding your tasking request by submitting a GET Tasking ID request. See the Tasking Guide to learn more about this request.

Tasking Validation Errors

The account does not have a tasking subscription

        "error_code": "price_not_set",
        "error_type": "authorization_error",
        "error_messages": [
            "Tasking imagery price is not set."
Action: Contact your Maxar Sales Representative to purchase a tasking subscription, or contact ARD Support.

The account has exceeded its Tasking usage allotment

       "error_code": "dollar_limit_exceeded",
        "error_type": "authorization_error",
        "error_messages": [
            "This order cannot be placed because it exceeds the remaining allotted dollars for tasking for this account. 50 dollars available; 250.50 dollars in this order."
Action: Contact your Maxar Sales Representative to purchase a tasking subscription, or contact ARD Support.

The AOI exceeds the maximum size limit

"error_code": "invalid_aoi",
"error_type": "invalid_request_error",
"error_messages": [
    "Bad Request: Problem with intersects/bbox field: Polygons must be equal to or less than 10000 sqkm; found one with area of 18289.23 sqkm."
Action: Reduce the size of the AOI and resubmit

The request body does not match the schema

"error_code": "invalid_request_body",
"error_type": "invalid_request_error",
"error_messages": [
    "$: Additional properties are not allowed ('datetime' was unexpected)"
Action: check for additional or incorrectly named properties in the request body.

The submitted value is not valid or the operator is not allowed for the property

"error_code": "invalid_request_body",
"error_type": "invalid_request_error",
"error_messages": [
    "$.query.aoi:cloud_free_percentage: {'lte': 50.0} is not valid under any of the given schemas"
Action: review the documentation for allowed values and operators.

Back to top