Intro to Ordering

Overview

The Ordering API lets you programmatically order imagery and analytics content. Your orders can then be downloaded, or the files can be delivered to the cloud storage location you specify.

To place an order, you need to know the "name" and "namespace" for the content type you're requesting. These parameters are included in the request URL. Content types have their own settings, which must be specified in the settings object of the order request.

Orderable content

Not all content is available to order through the Ordering API at this time. Refer to this table for orderable content.

Content	Namespace	Name	Description
Core Imagery	`imagery`	multiple	Satellite imagery.
Analysis-Ready Data	`imagery`	`analysis-ready`	Analysis-Ready COGs and accompanying metadata.
Precision3D Products	`3d`	multiple	DTM, DSM, buildings, and other 3D data.
Vivid Standard 30cm	`basemaps`	`vividstandard30`	Vivid Standard 30cm global mosaics.
Vivid Advanced 15cm	`basemaps`	`vividadvanced15`	Vivid Advanced 15cm basemaps.
CM-SAR (20 m)	`insights`	`cm-sar-ordering`	Change detection based on a multi-temporal stack of Sentinel 1A/1B data.
Object Detection data	`insights`	`object-detection`	Object detection bounding box vectors derived from an image.

Ordering API Requests

The following requests can be made to the Ordering API. The base path is api.maxar.com.

Note: The API interface uses the term pipeline to reference the process that creates and delivers the requested content. The output of the pipeline is the ordered content.

Request Type	Method	Path	Description
Place an Order	`POST`	`ordering/v1/pipelines/{namespace}/{name}/order`	Place an order for imagery or analytics content by pipeline.
Validate Order	`POST`	`ordering/v1/pipelines/{namespace}/{name}/validate`	Verify that the order passes validation checks before submission.
Get Order Details	`GET`	`ordering/v1/orders/{orderID}`	Get the details and status of an order request.
List User's Orders	`GET`	`ordering/v1/orders/user/{id}`	List the orders placed by a user.
List Events for an Order	`GET`	`ordering/v1/orders/{orderid}/events`	Retrieve a page listing of order events for a given order.
Cancel Order	`POST`	`ordering/v1/orders/{orderid}/cancel`	Cancels the order specified in the URL path. Orders cannot be canceled once the delivery process has started.
Estimate Usage	`POST`	`ordering/v1/pipelines/{namespace}/{name}/estimate`	Get a usage estimate for an order request before placing the order.
List Orders for User	`GET`	`ordering/v1/pipelines/{namespace}/{name}`	List orders for a specific user.
List Pipelines	`GET`	`ordering/v1/pipelines`	Lists the available content pipelines.
Get Pipeline	`GET`	`ordering/v1/pipelines/:namespace/:name`	Get details for a specific content pipeline.

Construct an Order request

To make an order request, include the content type's namespace and name in the path, and submit a JSON request body.

Order Request Path:

POST https://api.maxar.com/ordering/v1/pipelines/{namespace}/{name}/order

Order Request body

The request body for an order includes the following sections:

Name	Type	Required?	Description
`settings`	object	required	The settings object includes parameters specific to the type of content being ordered.
`output_configs`	array	required	The delivery configuration for your cloud storage location. Amazon S3, Azure, and Google Cloud Storage are supported.
`notifications`	array	optional, but recommended	The configuration for order notifications. Supported types are `email`, `sns`, and `http`.
`metadata`	object	optional	Supplemental information to attach to the order. For example, add a project name or ID.

Review the responses for GET pipeline for available options for each object in available pipelines. Notifications is the same for each pipeline and options for this object are outlined below.

Settings

The settings object contains the relevant settings for product options. Each has different settings - see the Orderable content table for details.

Output configuration

Orders can be delivered in the following ways:

Download, as a zip or tar file
Send to an AWS Commercial S3 bucket
Send to an Azure Cloud Storage Container
Send to a Google Cloud Storage bucket
Send to the MGP Pro UI

It is possible to deliver to multiple locations. The output configuration is specified by the output_configs array in the order body. Include any of the following output objects in the array.

Example configuration with multiple outputs:

"output_configs": [
  {
    "type": "download",
    "format": "zip"
  },
  {
    "type": "amazon_s3",
    "bucket" "your_bucket",
    "prefix": "your/prefix"
  }
]

See the Outputs guide for details on how to configure the different delivery outputs.

Notifications

Notifications can be configured to send messages to different outlets at different points during the order fulfillment process. These include:

Send an email to one or more addresses
Emit a message to an Amazon SNS topic
HTTP POST a JSON payload to a specified URL.

You can have multiple notification in a single order. Each notification can be configured with different levels of verbosity. For example, you can configure one notification to email only a "Success" or "Fail" message, while a second notification could send SNS notifications for each step of the ordering process from beginning to end.

Example notifications configuration:

"notifications": [
   {
    "type": "email",
    "target": "user@example.com",
    "level": "FINAL_ONLY"
  }
]

For more details on notification options, see Ordering Notifications.

Metadata

The metadata object can hold optional key-value data. Use this section to store your own order metadata.

metadata": {
  "project": "My Project",
  "description": "New Imagery"
}

Order Example

This example shows a "view-ready" imagery order with overrides. See the Content Pipeline table for links to other examples.

Order Request Path:

POST https://api.maxar.com/ordering/v1/pipelines/imagery/view-ready/order

Order Request:

{
    "settings": {
      "aoi": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -123.14830629447482,
              49.272523954428266
            ],
            [
              -123.14830629447482,
              49.24221441101426
            ],
            [
              -123.10082049428735,
              49.24221441101426
            ],
            [
              -123.10082049428735,
              49.272523954428266
            ],
            [
              -123.14830629447482,
              49.272523954428266
            ]

          ]
        ],
      },
      "overrides": {
        "product": {
          "product_details": {
            "compression": "DEFLATE",
            "acomp": "acomp",
            "file_format": "GeoTIFF",
            "product_option": "4BandPanSharpen",
            "output_bit_depth": 8,
            "dynamic_range_adjustment": "auto",
            "resampling_kernel": "CC",
            "projection_datum_option": "Geographic_WGS84_DecimalDegree"
          }
        }
      },
      "customer_description": "LG01_250704",
      "inventory_ids": [
        "B110001101F96100"
      ]
    
  },
    "output_configs": [ 
        {
            "type": "download",
            "format": "zip"
        }
      ],
    "notifications": [
      {
        "type": "email",
        "target":"user@example.com",
        "level": "INITIAL_FINAL"
      }
    ],

    "metadata": {
        "project_name": "Name your project"
    }
}  

Overview​

Orderable content​

Ordering API Requests​

Construct an Order request​

Order Request body​

Settings​

Output configuration​

Notifications​

Metadata​

Order Example​