API Quickstart¶
Last Updated: August 12, 2022
Overview¶
There are three ways to interact with Maxar's ARD API:
-
a Python-based SDK
-
A Command line interface (CLI)
-
a Postman collection for JSON API requests
Note: We recommend using the SDK or CLI as the most convenient way to select and order ARD imagery.
Documentation
Quickstart tutorial¶
This Quickstart example will walk you through selecting and ordering ARD imagery by making API calls.
API requests can be made using the API client of your choice. We offer a collection file and environment for Postman users.
See Developer Tools for Postman instructions and download links.
ARD API¶
The root url for the ARD API is:
https://ard.maxar.com/api/v1
Step 1: Get an access token¶
An access token is needed to make requests to the Maxar ARD API. A token lasts for 12 hours.
Example request:
POST /auth/authenticate
{
"grant_type": "password",
"username": "[username@example.com]",
"password": "[password]"
}
Example response:
The token response includes an access-token. This is what you'll use to access the ARD API.
{
"access_token": "{access token}",
"token_type": "Bearer",
"expires_in": 43200,
"refresh_token": "{refresh token}"
}
Documentation
Step 2: Create an S3 bucket policy to give Maxar write access¶
Maxar delivers ordered files to your personal cloud storage location and prefix. To write files to your bucket, Maxar ARD needs "write" permissions.
S3 Users¶
-
Create an AWS bucket for delivery if you don't already have one. You can create a new bucket from the AWS Management Console.
-
Add a bucket policy that gives Maxar permission to write data to your bucket. This policy is limited to write access. Maxar will not access or read files in your bucket.
The policy only needs to be set up once on a bucket. Maxar's permissions can be revoked by deleting the policy or editing it to deny access.
To learn how to set up or revoke the bucket policy using the AWS Management Console, see AWS bucket policy.
Azure and Google Cloud Storage users¶
Azure and Google cloud storage users, you'll create temporary credentials for your specified platform, and then you will save them to the ARD credentials service.
Step 3: Select ARD tiles to order¶
Imagery can be selected based on a set of criteria or by acquisition IDs and an area of interest (AOI) in WKT, GeoJSON geometry, or Bbox format. The "stack depth" field lets you determine the number of images to return per cell. If the stack depth is not specified, a maximum of 5 images per cell will be returned.
To see examples of bounding box, WKT, and GeoJSON geometry inputs in a select request, see Area of Interest (AOI) Examples and Guidelines.
Example request
POST /select
{
"datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
"bbox": [-106.8, 35.1, -106.4, 35.4],
"stack_depth": 3,
"query": {
"platform": {
"in": ["worldview-01", "worldview-02", "worldview-03", "worldview-4", "geoeye-01"]
},
"aoi:cloud_free_percentage": {
"gte": 95.0
},
"aoi:data_percentage": {
"gte": 75.0
}
}
}
See Selecting Imagery to Order to learn how construct an imagery selection request.
Example Response:
Status: 200 OK
{
"id": "5701532359835563578",
"response_timestamp": "2021-07-15T19:47:07Z",
"duration": "0:00:05.135000",
"request_details": {
"datetime": "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z",
"bbox": [
-106.8,
35.1,
-106.4,
35.4
],
"stack_depth": 3,
"query": {
"platform": {
"in": ["worldview-01", "worldview-02", "worldview-03", "worldview-4", "geoeye-01"]
},
"aoi:cloud_free_percentage": {
"gte": 95.0
},
"aoi:data_percentage": {
"gte": 75.0
},
"view:sun_elevation": {
"gte": 5
},
"instruments": {
"not-contains": "SWIR"
}
}
},
"status": "SUCCEEDED",
"stack_depth_summary": {
"filled": 1,
"partial": 39,
"empty": 16,
"total": 56
},
"links": {
"self": "https://ard.maxar.com/api/v1/select/request/5701532359835563578",
"status": "https://ard.maxar.com/api/v1/select/request/5701532359835563578",
"html": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.html",
"geojson": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.geojson",
"geojsonl": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.geojsonl",
"stac": "https://ard.maxar.com/api/v1/select/files/5701532359835563578.stac"
},
"usage": {
"limits": {
"limit_sqkm": -1,
"annual_subscription_fee_limit": 100500,
"fresh_imagery_fee_limit": -1,
"standard_imagery_fee_limit": -1,
"training_imagery_fee_limit": -1
},
"area": {
"training_imagery_sqkm": 0,
"total_imagery_sqkm": 1313,
"fresh_imagery_sqkm": 0,
"standard_imagery_sqkm": 1313,
"estimate": true
},
"cost": {
"fresh_imagery_cost": 0,
"standard_imagery_cost": 14,
"training_imagery_cost": 0,
"total_imagery_cost": 140,
"estimate": true
},
"available": {
"available_sqkm": -1,
"total_imagery_balance": 100360,
"fresh_imagery_balance": -1,
"standard_imagery_balance": -1,
"training_imagery_balance": -1
},
"usage_as_of": "2021-07-20T20:59:18Z"
}
}
The response includes the original request, links to files about the selection, and an estimate of usage that will be incurred if the imagery is ordered.
You can refine your selection as many times as you need to before ordering. Usage charges are incurred at the time the order is placed and successfully delivered.
Retain the "id" from this response to place an order for the selected imagery.
For more information on constructing a select response and visualizing the results, see:
How to select ARD imagery to order
Step 4: Order ARD imagery¶
The simplest way to order ARD imagery is to place an order using the ID from the "select" response.
Example request using the select ID to order:
{
"select_id": "[the ID from your imagery select response]",
"output_config": {
"amazon_s3": {
"bucket": "example-bucket",
"prefix": "prefix_name"
}
},
"dry_run": true,
"bundle_adjust": true,
"notifications": [
{
"type": "email",
"address": "[your email address]"
}
]
}
It is possible to skip the "select" step and place an order using a set of acquisitions IDs and optionally, an AOI. However, placing an order does not provide usage estimates or a visualization link. See How to Place an Order to learn how to construct an order.
Example order response:
{
"id": "5453676662402868605",
"links": {
"status": "https://ard.maxar.com/order/order/5453676662402868605"
}
}
Documentation: How to Place an Order
Step 5: Check the status of an order¶
Orders can take between a few hours and several days to be delivered to your S3 bucket. You can check the status of your order with an API request.
Example order status request:
GET /order/status/:order_ID
The response to an order status request includes the status of the order and the content of the order placed. It also displays usage data for the order.
Example response:
{
"id": "1234567890...",
"status": "RUNNING",
"status_message": "Ordering imagery",
"acquisition_details": [
{
"id": "104001004D4CE000",
"status": "ORDERING"
},
{
"id": "103001009E8C7C00",
"status": "ORDERING"
},
{
"id": "103001007B478000",
"status": "ORDERING"
}
],
"order": {
"id": "1234567890",
"account": "",
"user_id": "",
"acquisitions": [],
"intersects": [],
"bbox": [],
"format": [],
"select_id": "0987654321",
"output_config": {
"role_arn": "(optional) iam role to write to outside AWS account",
"bucket": "user-bucket",
"prefix": "directory-path"
},
"bundle_adjust": false,
"usage": {
"area": {
"fresh_imagery_sqkm": 0,
"standard_imagery_sqkm": 0,
"training_imagery_sqkm": 0,
"total_imagery_sqkm": 0,
"estimate": false
},
"cost": {
"fresh_imagery_cost": 0,
"standard_imagery_cost": 0,
"training_imagery_cost": 0,
"total_imagery_cost": 0,
"estimate": false
}
},
"failure_reason": null,
"notifications": [
{
"type": "email",
"address": "your-email@gmail.com"
}
]
},
"response_timestamp": "2019-12-02T01:23:45Z"
}
Documentation:
Step 5: Access your ARD imagery¶
ARD orders are delivered to the cloud storage location specified in your request. Each order includes the ARD GeoTIFFs and accompanying metadata, along with information about the order and its contents.
To learn about the directory structure and files for your delivery, see the documentation.
Documentation Output files and Directory Structure