Skip to content

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:SDK

Quickstart: CLI

SDK and CLI 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]"
}
If you are using Postman, you will set up an "environment" that includes your username and password. The GetToken request in the Postman collection is set up to use these credentials from the environment file when you hit "send" on the request url.

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}"
}
The "refresh token" can be used to request a new token without passing your credentials. See the "Get a Token" documentation listed below for details.

Documentation

Get a token

Authentication API reference

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 (account_and_user_administration/credentials_service.md).

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.

**Note: GeoJSON must be a geometry. GeoJSON feature collection is not a valid input.

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

Select API reference

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]"
        }
    ]
}
Note: We recommend you use a new prefix for each order to avoid the possibility of overwriting data. See adding imagery to an existing prefix for more information.

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

/Order API reference

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:

Order ARD Imagery

Order API reference

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

Back to top