Tasking Resource¶

Last Updated: December 16, 2022

Tasking¶

/tasking

Request imagery collection from one or more Maxar satellites.

Tasking requests¶

http method	path	name	description
POST	/tasking	Submit a Tasking request	Request imagery collection from one or more Maxar satellites for a specified AOI and date range.
GET	/tasking/{tasking_id}	GET tasking details	A read-only method for seeing details surrounding your tasking request.

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.

Submit a Tasking request¶

Example request:¶

POST https://ard.maxar.com/api/v1/tasking

Example request body:

{
    "name": "albuquerque tasking request",
    "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": false,
    "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.	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 configuration object	required	The order details for placing an order when collected imagery is available.	see order details section below.	n/a
dry_run	optional	Include `"dry_run": true` to validate your request and see usage costs before submitting.	true/false	false

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`	For the specified AOI, only collect imagery tht is is greater than or equal to the specified value.	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, not-contains	worldview-02, worldview-03, geoeye-01	`"platform": {"in": ["worldview-02", "geoeye-01"]}`

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

Operators¶

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

gte: greater than or equal to lte: less than or equal to

Order config¶

Imagery collected to meet a tasking request is automatically ordered and delivered to your cloud storage location. to enable this, the order configuration is part of the tasking request.

The order configuration object is made up of the following:

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.
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 Order API Reference.

Example dry run validation response:¶

200 OK

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

object 1	object 2	field	description
data		message	Tasking dry run validation successful.
usage	area	tasking_imagery_sqkm	The total number of sq km in the tasking request.
usage	cost	tasking_imagery_cost	The cost of the tasking order. This is charged when the tasking request is submitted.
usage	limits	tasking_imagery_fee_limit	The total tasking allowance for the account in U.S. dollars.
usage	available	tasking_imagery_balance	The remaining tasking allowance for the account in U.S. dollars.
usage	usage_as_of		the date and time the validation request was made. Remaining usage is calculated up to the time of validation request.
links	request		A link to the tasking request body.
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.

Example Tasking response:¶

200 OK

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

object	field	description
data	id	the unique identifier for the tasking request, also referred to 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	A link to the tasking request body.
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.

GET tasking details¶

Example request¶

GET https://ard.maxar.com/api/v1/tasking/{tasking_id}

Path parameters¶

parameter	description	example
tasking_id	To view details surrounding your tasking request, input your tasking ID in the path.	6067693596352811694

Example response body:¶

{
  "data": {
    "id": "tasking_id",
    "date_created": "2022-12-03T00:44:02Z",
    "date_modified": "2022-12-03T00:44:03Z",
    "name": "my_order_name",
    "description": "non-super tasking tests",
    "account_id": "my_account_id",
    "user_id": "my_user_id",
    "active": true,
    "intersects": null,
    "bbox": [
      29.531249999999996,
      59.88893689676583,
      30.234375000000014,
      60.239811169998916
    ],
    "query": {
      "view:sun_elevation": {
        "gte": 5
      },
      "aoi:cloud_free_percentage": {
        "gte": 1
      },
      "view:off_nadir": {
        "lte": 30
      },
      "platform": {
        "in": [
          "worldview-02",
          "geoeye-01"
        ]
      }
    },
    "order_config": {
      "output_config": {
        "amazon_s3": {
          "bucket": "my_bucket_name",
          "prefix": "my_prefix_name"
        }
      },
      "settings": {
        "bundle_adjust": false,
        "healthy_vegetation_mask": false,
        "terrain_shadow_mask": false,
        "water_mask": false,
        "pan_flare_mask": false,
        "ms_saturation_mask": false
      },
      "metadata": {
        "order_from": "tasking-api",
        "branch": "main"
      },
      "notifications": [
        {
          "type": "email",
          "address": "shea.barnes@myemail.com"
        },
        {
          "type": "sns",
          "topic_arn": "arn:aws:sns:us-east-1:817603998277:testing-topic-OpenTestTopic-1VOUECFDHER34"
        }
      ]
    },
    "start_collect": "2022-12-04T00:00:00Z",
    "end_collect": "2023-06-24T00:00:00Z",
    "monitor_id": "monitor_id",
    "usage": {
      "tasking_imagery_sqkm": 1530.746,
      "tasking_imagery_cost": 15.31
    },
    "percent_remaining": 83.79,
    "remaining_aoi": "{\"type\": \"Polygon\", \"coordinates\": [[[29.53125, 59.8889369], [29.53125, 60.23981117], [30.110816232738756, 60.23981117], [30.110901402, 60.22640569], [30.111155752, 60.19678433], [30.111487801, 60.163222596], [30.111607092, 60.148199847], [30.111644042207057, 60.144395622105705], [30.234375, 60.14369575], [30.01356621, 60.14495491], [30.01365621, 60.11532729], [30.01375887, 60.07159983], [30.01385325, 60.02782011], [30.01388373, 60.01728465], [30.234375, 60.01580459], [30.234375, 59.8889369], [29.53125, 59.8889369]]]}"
  },
  "links": {
    "monitor": "https://ard.maxar.com/api/v1/monitor/config/tasking_id",
    "history": "https://ard.maxar.com/api/v1/monitor/history/tasking_id",
    "request": "https://api.ard.maxar.com/tasking/tasking_id"
  },
  "request_timestamp": "2022-12-09T16:52:35Z",
  "response_timestamp": "2022-12-09T16:52:41Z",
  "request_duration": 6
}

Response body objects¶

field	description	example
`id`	The Tasking ID for the tasking that made the match.	`"id": "5778229983415384..."`
`date_created`	The date your tasking order was created.	`"date_created": "2022-12-03T00:44:02Z"`
`date_modified`	The date your tasking order was last modified.	`"date_modified": "2022-12-03T00:44:03Z"`
`name`	The name of your tasking order.	`"name": "my_order_name"`
`description`	A description of the monitor to help identify it later.	`"non-super tasking tests`
`account_id`	The ID for the account where the credentials have beeen registered.	`557471230760500000`
`active`	The user's active/inactive status. A value of "true" means the user is active and has access to ARD resources. A value of "false" means the user record has been deactivated.	`"active": true`
`intersects`	If the AOI was submitted in WKT or GeoJSON geometry format, it will display here. If no "intersects" value was submitted, this value for this field will be "null".	`"intersects": null`
`bbox`	If the AOI was submitted as a bbox, it will display here. If no bbox was submitted, the value for this field will be "null".	`"bbox": [44.663653, -6.042026, 44.853207, -5.901495]`
`query`	The query parameters the monitor is using to find matching imagery.	See Query fields table here.
`order_config`	Where your order is set up to output to.	`"order_config": { "output_config": { "amazon_s3": { "bucket": "my_bucket_name", "prefix": "my_prefix_name" }`
`settings`	The settings parameters the monitor will run on your imagery once it is found.	See "Settings object" here.
`metadata`	Various metadata attributes about your tasking order.	`"metadata": { "mixed_object": { "anotherbool": true, "object_object": "outer", "objectively_oject": "inner" }, "number": 21, "boolean": false, "order_from": "tasking-api", "string": "cow", "mixed_array": [ "word", 3, { "array_object": "first", "array_otherobject": "second" } ], "float": 9.876543210123456, "branch": "main" }`
`notifications`	How and where you have chosen to be notified when your tasking order is updated.	`"notifications": [{ "type": "email", "address": "shea.barnes@myemail.com" }`
`start_collect`	When your tasking order began collecting data	`"start_collec": "2022-12-04T00:00:00Z"`
`end_collect`	The last date your tasking order may take images.	`"end_collect": "2023-06-24T00:00:00Z"`
`usage`	How much of your subscription your tasking request has used, in both cost and square kilometers.	`"usage": {"tasking_imagery_sqkm": 1530.746, "tasking_imagery_cost": 15.31`
`percent_remaining`	The percentage of the AOI that has not been matched yet.	`96.2%`
`remaining_aoi`	The coordinates for the remaining area that has not been fulfilled with an imagery match yet.	"{\"type\": \"Polygon\", \"coordinates\": [[[29.53125, 59.8889369], [29.53125, 60.23981117], [30.110816232738756, 60.23981117], [30.110901402, 60.22640569], [30.111155752, 60.19678433], [30.111487801, 60.163222596], [30.111607092, 60.148199847], [30.111644042207057, 60.144395622105705], [30.234375, 60.14369575], [30.01356621, 60.14495491], [30.01365621, 60.11532729], [30.01375887, 60.07159983], [30.01385325, 60.02782011], [30.01388373, 60.01728465], [30.234375, 60.01580459], [30.234375, 59.8889369], [29.53125, 59.8889369]]]}"
`links`	Links to various extra information about your order.	see Example Tasking response.
`request_timestamp`	The time the request was returned.	`"2022-12-09T16:52:35Z"`
`response_timestamp`	The time the response was returned.	`"2022-12-09T16:52:41Z"`
`request_duration`	The time in seconds between when the request was submitted and the response was returned.	`6`