How to Place a Tasking Request
Note: These instructions only apply to tasking orders placed via the MGP Tasking API.
In this tutorial, we'll walk through the steps to create an MGP tasking request. For more detailed information, see Tasking API reference.
Prerequisite: Cloud storage setup
Before you place a tasking request, make sure your delivery location is set up to allow Maxar to write data to it. The output files from your tasking order can be delivered to one of the following cloud types:
Prerequisite: MGP API Key
An MGP API key provides authentication to make MGP API requests. An OAuth bearer token can also be used.
API URLs
To place an order, validate your order request, or get a usage estimate, make a request to the URL in the table below with a JSON request body. Follow the tutorial to create a request body.
| Request | Description | Request URL |
|---|---|---|
| Submit a Tasking request | Place a tasking request. | POST https://api.maxar.com/tasking/v1/tasking |
| Validate a request body before submitting | See if your request body is valid before submitting your tasking order. | POST https://api.maxar.com/tasking/v1/tasking?validation_only=true |
| Quote a tasking request | Get a usage estimate quote for your tasking request before placing it. | POST https://api.maxar.com/tasking/v1/tasking/quote |
Tasking example
We'll use the following example in our tutorial. This example JSON request body will collect a 50 cm color image and process and deliver it as a system-ready (1B) image. If you use this example, be sure to set the start and end dates to a future date.
{
"start_datetime": "2025-01-01T00:00:00Z",
"end_datetime": "2025-03-01T00:00:00Z",
"aoi_geojson": {
"coordinates": [
[
[-105.024490, 39.675484],
[-104.867935, 39.675484],
[-104.867935, 39.784268],
[-105.024490, 39.784268],
[-105.024490, 39.675484]
]
],
"type": "Polygon"
},
"max_cloud_cover": 30,
"max_off_nadir_angle": 30,
"collect_gsd": 0.5,
"min_sun_elevation_angle": 15,
"order_templates": [
{
"pipeline": "imagery/system-ready",
"template": {
"settings": {
"customer_description": "50 cm 1B imagery",
"inventory_ids": ["$.id"],
"aoi": "$._aoi_intersection"
},
"output_configs": [
{
"type": "amazon_s3",
"bucket": "example-bucket",
"prefix": "example-prefix"
}
]
}
}
],
"end_use_code": "AGR",
"tasking_priority": "SelectPlus"
"tasking_notifications": [{
"type": "email",
"target": "user@example.com",
"level": "INTERMEDIATE"
}]
}
1. Date and Time
The collection time frame is determined by the start date and the end date. Both are required.
start_datetimemust be set at least 5 minutes in the future.end_datetimemust be set at least 10 minutes in the future.
"start_datetime": "2025-01-01T00:00:00Z",
"end_datetime": "2025-03-01T00:00:00Z",
Dates must use ISO 8601 standards and must specify a time zone designator of either UTC or an offset from UTC.
The following are all valid datetime formats.
"2024-04-02T00:00Z"
"2024-04-02T00:00:00Z"
"20240402T00:00+0000"
"2024-04-02T4:00+04:00"
"2024-04-02T04:00+04:00"
"2024-04-01T22:00-02"
2. Area of Interest (AOI)
AOI format and rules
Your AOI is submitted in the aoi_geojson field. It must be a polygon in GeoJSON format.
"aoi_geojson": {
"coordinates": [
[
[-105.024490, 39.675484],
[-104.867935, 39.675484],
[-104.867935, 39.784268],
[-105.024490, 39.784268],
[-105.024490, 39.675484]
]
],
"type": "Polygon"
-
Geometry type: A GeoJSON geometry polygon.
-
Minimum AOI size: 50 sq kms.
-
Maximum AOI size:1000 sq kms.
-
Minimum width: The minimum polygon width is 2000 meters.
-
Vertices: The maximum number of vertices is 1000. Vertices should be spaced at a minimum of 1 - 2 meters apart.
High demand areas
High demand countries include: Armenia, Azerbaijan, Bahrain, Benin, China (East), Colombia, Congo, Cyprus, Ecuador, Gabon, Gaza Strip, Georgia, Iran, Iraq, Israel, Japan, Jordan, Kuwait, Lebanon, North Korea, Nigeria, Oman, Qatar, Saudi Arabia, Singapore, South Korea, Syria, Taiwan, Togo, Turkey, Turkmenistan, Ukraine, United Arab Emirates, West Bank, and Yemen
3. Tasking parameters
You can include additional tasking parameter in your request (optional). The values you specify for the parameters must all be met for a collection to occur. More parameters and tighter restrictions can hinder the collection from taking place.
This set of tasking parameters is taken from the example earlier in this document. The complete list of tasking parameters and allowed values can be found at Tasking Parameters.
"max_cloud_cover": 30,
"max_off_nadir_angle": 30,
"collect_gsd": 0.5,
"min_sun_elevation_angle": 15
4. Order template
Once the imagery is collected to fulfill an MGP tasking request, it is sent to the MGP ordering API to be processed by one of the "core imagery" pipelines. When the files are ready, they are delivered to the specified cloud delivery location. The instructions for ordering, processing, and delivering collected imagery are specified in the order_templates object.
Example order template:
"order_templates": [
{
"pipeline": "imagery/system-ready",
"template": {
"settings": {
"customer_description": "string",
"inventory_ids": ["$.id"],
"aoi": "$._aoi_intersection"
},
"output_configs": [
{
"type": "amazon_s3",
"bucket": "example-bucket",
"prefix": "example-prefix"
}
]
}
}
],
Pipeline
The pipeline field tells the ordering system which core imagery product the collected image should be processed as. The pipeline name consists of a namespace and a name. The allowed values are:
imagery/system-ready
imagery/view-ready
imagery/view-ready-ortho
imagery/map-ready
See Core Imagery Default Recipes for more information about these core imagery products.
Settings
The "settings" section tells the MGP ordering system the catalog IDs to order and the AOI to apply. It also requires a customer description for the order. The inventory_ids and aoi fields use placeholders to populate the values.
Example:
"settings": {
"customer_description": "Albuquerque NM project",
"inventory_ids": ["$.id"],
"aoi": "$._aoi_intersection"
}
Placeholders are used to populate the order template with values not currently known, or to populate the order template with a value referenced elsewhere in the request.
This table defines the values allowed for the fields in the "settings" object. All fields are required.
| Field Name | Description | Allowed Values |
|---|---|---|
| customer_description | A brief description to help you identify the order. | The value must be a "string." |
| inventory_ids | Use the placeholder ["$.id"] as the value. This tells the ordering system to order the imagery collected for this request. No other value will be accepted for this field. | "inventory_ids": ["$.id"] |
| aoi | Use the placeholder "$._aoi_intersection" as the value. This tells the ordering system to intersect the ordered imagery with the AOI defined in the aoi_geojson field from the tasking parameters. No other value will be accepted. | "aoi": "$._aoi_intersection" |
Order delivery (output_configs)
The values in the output_configs object tell the ordering system where to deliver the imagery once it's collected and processed. MGP needs "write" access to your cloud storage location in order to deliver the ordered files. Each section below gives an example output_configs object and a link to setup documentation.
Amazon S3
"output_configs": [
{
"type": "amazon_s3",
"bucket": "example-bucket",
"prefix": "example-prefix"
}
]
To give Maxar "write" access to your S3 bucket, set up a bucket policy before you place a tasking order. This allows the ordered imagery to be delivered to your S3 bucket. See S3 bucket and policy setup
Azure cloud storage
"output_configs": [
{
"azure_blob_storage": {
"sas_url": "Azure SAS URL string goes here",
"container": "my-mgp-container",
"prefix": "prefix-1"
}
]
To give Maxar "write" access to your Azure storage container, create a SAS URL with "write" permissions. This allows the ordered imagery to be delivered to your container. See Azure Cloud Storage.
Google cloud storage
"output_configs": [
{
"google_cloud_storage": {
"service_credentials": "... base64-encoded credentials string ...",
"bucket": "my-mgp-bucket",
"prefix": "prefix-1"
}
]
To give Maxar "write" access to your Google cloud storage bucket, set up your account with the permissions listed in the Google cloud storage setup documentation. Then from your account, generate a JSON service key and then convert the key to a base-encoded credentials string.
5. End Use Code
A tasking request requires an end use code to identify the intended use of the ordered imagery. See allowed end use code values.
Example:
"end_use_code": "AGR",
Important: Avoid using the "OTH" end use code which means "other". This requires a manual review process and may delay fulfillment of your tasking order or cause it to be rejected. Use the code that most closely matches your intended use.
6. Priority
The tasking priority will be "Select" unless "SelectPlus" is specified. See Priority in the Intro to Tasking.
"tasking_priority": "SelectPlus"
7. Tasking notifications
The MGP tasking API supports the following notification types: email, sns, or http delivery. A request can include one or more notification types. See the examples below. The tasking_notifications object is not required. If it's not included, no notifications will be sent.
Notification level determines what notifications you receive for your tasking order. For details, see Tasking Notifications.
Example: Email
"tasking_notifications": [{
"type": "email",
"target": "user@example.com",
"level": "FINAL_ONLY"
}]
The target field accepts a single email or a comma-separated list of emails.
Example:
"target": "email1@email.com,email2@email.com",
Example: SNS
"tasking_notifications": [{
"type": "sns",
"target": "arn:aws:sns:us-east-2:123456789012:YourTopic",
"config": {
"requires_message_group_id": true,
"requires_message_deduplication_id": true,
},
"level": "FINAL_ONLY",
}]
Example: HTTP
"tasking_notifications": [{
"type": "http",
"target": "https://your-service-url/order/",
"config": {
"headers": {
"Authorization": "Bearer 12345",
"X-CUSTOM-HEADER": "some value",
}
},
"level": "INTERMEDIATE",
}]
Example: Multiple notification types
"tasking_notifications": [{
"type": "email",
"target": "user@example.com",
"level": "INTERMEDIATE"
}],
"tasking_notifications": [{
"type": "sns",
"target": "arn:aws:sns:us-east-2:123456789012:YourTopic",
"config": {
"requires_message_group_id": true,
"requires_message_deduplication_id": true
},
"level": "FINAL_ONLY"
}]
Status, validation, and errors
Validation occurs during multiple stages of the tasking, collection, processing, and delivery workflow. "Synchronous" validation checks are made at the time the tasking request is submitted. "Asynchronous" validation checks occur throughout the process. These checks are explained in the Validation and Errors guide. Status definitions can be found in the API reference section, under Tasking Status.
To check on the status of a tasking request, see Get the status and details of a tasking request.
Canceling a tasking request
When a tasking request is canceled, it will be ended and the satellites will not attempt to collect imagery. You can add a request body to a Cancel Tasking request to provide the reason for cancellation.
{
"reason": "user-provided reason for canceling the request."
}
Tasking API reference
Place or validate a tasking request