Online Ordering

Overview

The Online Ordering pipeline offers simplified options to order satellite imagery. The only required input is the acquisition ID of an image. Optionally, the image can be clipped to an AOI. The minimum AOI size is 0.1 sq.km.

The delivered images are formatted as Cloud Optimized GeoTIFF. Dynamic Range Adjustment (DRA) has been applied to convert the images to a standard visual 8-bit pixel values. Multispectral images are delivered as pan-sharpened RGB bands, while panchromatic images are single-band grayscale. The images are delivered in the UTM projection that best fits the image or AOI.

Note: Only images found in the cloud-optimized-archive collection can be ordered. See Raster Analytics - Check Availability and Discovery API - Searching Collections.

Technical details

Online Ordering uses the Raster Analytics API to generate the image. It is similar in concept to using a tool like gdal_translate to convert the Raster Analytics virtual GeoTIFF to a new file.

The following parameters are passed to Raster Analytics by the pipeline to generate the pixels in the delivered image:

Multispectral

function="pansharp_ortho"
collect_identifier="<ID>"
crs="UTM" 
bands="red,green,blue" 
dra="true"
acomp="false"
hd="false"

Panchromatic (WV01 only)

function="ortho"
collect_identifier="<ID>"
crs="UTM" 
bands="pan" 
dra="true"
acomp="false"
hd="false"

Generating an image directly from Raster Analytics offers more configuration and customization of outputs versus the Online Ordering pipeline. However, the ability to asynchronously place orders may be advantageous, especially when requesting large areas.

Ordering Online imagery

This documentation describes the requirements that are specific for ordering imagery through the Online Imagery pipeline. To see the full description of an order request, see the Ordering API Guide.

When you place an order for an image, you will:

include the name and the namespace in the URL path.
include the settings object for the pipeline in the order request body.

Content Type	Namespace	Name
Online Ordering	`imagery`	`online-ordering`

Supported requests

Base URL: https://api.maxar.com

Request Type	Path	Description
Place an order	`POST /ordering/v1/pipelines/imagery/online-ordering/order`	Places an order to the Online Ordering content pipeline.
Validate order	`POST /ordering/v1/pipelines/imagery/online-ordering/validate`	Verifies that the request JSON is formatted correctly and that the settings are valid. Also returns estimated usage data.
Estimate usage	`POST /ordering/v1/pipelines/imagery/online-ordering/estimate`	Returns estimated usage for the order.
Get the details of an order	`GET /ordering/v1/orders/{id}`	Submit an order ID to view the order's details and status information.
Cancel an order	`POST /ordering/v1/orders/{id}/cancel`	Submit an order ID to cancel the order before the delivery process begins.

Place an order

Request URL

An Order request URL requires a "namespace" and a "name. These tell the Ordering API what product to order.

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

For Online Ordering, these are:

Namespace: imagery
Name: online-ordering

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

Online Ordering settings

When placing an order, some information is specific to the type of content selected. This information is grouped together as "settings".

Parameter	Required	Description	Example
inventory_ids	required	An array containing a single acquisition ID to order. See note below.	`"inventory_ids": ["10300100B3841C00"]`
aoi	optional	A GeoJSON geometry or feature collection to clip the image.	See ordering request example.
customer_description	optional	Description	`"customer_description": "Project 3"`

Note: Online Ordering was designed to be a simplified alternative to Core Imagery and uses the same parameter names. While Core Imagery can process multiple images passed in the inventory_ids parameter, this pipeline can only process a single image at a time. Therefore you must still pass an array and it will only have one value.

Example settings object

    {
        "customer_description": "Denver WV01",
        "inventory_ids": [
            "102001010F8B1E00"
        ],
        "aoi": {
            "coordinates": [
                [
                    [
                        -104.79930562870985,
                        39.85748702517549
                    ],
                    [
                        -104.79930562870985,
                        39.836134757672966
                    ],
                    [
                        -104.75826398722565,
                        39.836134757672966
                    ],
                    [
                        -104.75826398722565,
                        39.85748702517549
                    ],
                    [
                        -104.79930562870985,
                        39.85748702517549
                    ]
                ]
            ],
            "type": "Polygon"
        }
    }

Example Online Ordering order

{
    "settings": {
        "customer_description": "Denver WV01",
        "inventory_ids": [
            "102001010F8B1E00"
        ],
        "aoi": {
            "coordinates": [
                [
                    [
                        -104.79930562870985,
                        39.85748702517549
                    ],
                    [
                        -104.79930562870985,
                        39.836134757672966
                    ],
                    [
                        -104.75826398722565,
                        39.836134757672966
                    ],
                    [
                        -104.75826398722565,
                        39.85748702517549
                    ],
                    [
                        -104.79930562870985,
                        39.85748702517549
                    ]
                ]
            ],
            "type": "Polygon"
        }
    },
    "output_configs": [
        {
            "type": "download",
            "format": "zip"
        }
    ],
    "notifications": [
        {
            "type": "email",
            "target": "user@example.com",
            "level": "FINAL_ONLY"
        }
    ],
    "metadata": {
        "project_name": "Denver Project"
    }
}

See the Outputs and Notifications guides for more information on these sections of the order payload.

Example Online Ordering order response

    {
  "data": {
    "id": "6693768007153061062",
    "date_created": "2025-04-14T20:22:08Z",
    "date_modified": "2025-04-14T20:22:11Z",
    "creator_id": "f:1234-5678-9999",
    "creator_group_id": "99",
    "pipeline_id": "imagery/online-ordering",
    "output_configs": [
      {
        "type": "download",
        "format": "zip"
      }
    ],
    "notifications": [
      {
        "type": "email",
        "target": "user@example.com",
        "level": "FINAL_ONLY"
      }
    ],
    "metadata": {
      "project_name": "Denver Project"
    },
    "status": "RECEIVED",
    "status_details": {},
    "cancellation_requested": false,
    "process_details": {},
    "delivery_details": {},
    "order_links": {
      "self": "https://api.maxar.com/ordering/v1/orders/6693768007153061062",
      "events": "https://api.maxar.com/ordering/v1/orders/6693768007153061062/events"
    },
    "settings": {
      "customer_description": "Denver WV01",
      "inventory_ids": [
        "102001010F8B1E00"
      ],
      "aoi": {
        "coordinates": [
          [
            [
              -104.79930562870985,
              39.85748702517549
            ],
            [
              -104.79930562870985,
              39.836134757672966
            ],
            [
              -104.75826398722565,
              39.836134757672966
            ],
            [
              -104.75826398722565,
              39.85748702517549
            ],
            [
              -104.79930562870985,
              39.85748702517549
            ]
          ]
        ],
        "type": "Polygon"
      }
    }
  },
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/online-ordering/order"
  },
  "request_timestamp": "2025-04-14T20:22:05Z",
  "response_timestamp": "2025-04-14T20:22:13Z",
  "request_duration": 8
}

Validate an order request

To validate your order before placing it, send your request body to the /validate endpoint first.

POST https://api.maxar.com/ordering/v1/pipelines/imagery/online-ordering/validate

This will verify that your request is formatted correctly and contains the required settings and allowed values for those settings.

Validate order example 200 response

Status: 200 OK

{
  "data": {
    "message": "validation successful"
  },
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/online-ordering/validate"
  },
  "request_timestamp": "2025-04-14T20:26:44Z",
  "response_timestamp": "2025-04-14T20:26:48Z",
  "request_duration": 4
}

Validate order example 400 response

In this example, the order did not pass validation because a field name was incorrect.

Status: 400 Bad Request

{
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/online-ordering/validate"
  },
  "request_timestamp": "2025-04-14T20:29:32Z",
  "response_timestamp": "2025-04-14T20:29:40Z",
  "request_duration": 8,
  "error": {
    "error_code": "invalid_request_body",
    "error_type": "invalid_request_error",
    "error_messages": [
      "Invalid order settings: $: Additional properties are not allowed ('inventoryIDs' was unexpected)",
      "Invalid order settings: $: 'inventory_ids' is a required property"
    ]
  }
}

Get a usage estimate

The /estimate endpoint returns a usage estimate and a copy of the JSON request body.

POST https://api.maxar.com/ordering/v1/pipelines/imagery/online-ordering/estimate

Estimate order example 200 response

Status: 200 OK

{
  "data": {
    "usage_estimate": [
      {
        "pipeline_id": "imagery/online-ordering",
        "metrics": [
          {
            "units": "sqkm",
            "quantity": 8.327,
            "description": "Imagery less than or equal to 90 days old",
            "usage_details": {}
          },
          {
            "units": "feature_count",
            "quantity": 1,
            "description": "Imagery less than or equal to 90 days old",
            "usage_details": {}
          },
          {
            "units": "tile_count",
            "quantity": 434.1251102224388,
            "description": "Imagery less than or equal to 90 days old",
            "usage_details": {}
          }
        ],
        "product_id": 240,
        "date_reported": "2025-04-14T20:40:15Z"
      }
    ],
    "order_config": {
      "pipeline_id": "imagery/online-ordering",
      "output_configs": [
        {
          "type": "download",
          "format": "zip"
        }
      ],
      "notifications": [
        {
          "type": "email",
          "target": "user@example.com",
          "level": "FINAL_ONLY"
        }
      ],
      "metadata": {
        "project_name": "Denver Project"
      },
      "settings": {
        "customer_description": "Denver WV02",
        "inventory_ids": [
          "103001011107E600"
        ],
        "aoi": {
          "coordinates": [
            [
              [
                -104.79930562870985,
                39.85748702517549
              ],
              [
                -104.79930562870985,
                39.836134757672966
              ],
              [
                -104.75826398722565,
                39.836134757672966
              ],
              [
                -104.75826398722565,
                39.85748702517549
              ],
              [
                -104.79930562870985,
                39.85748702517549
              ]
            ]
          ],
          "type": "Polygon"
        }
      }
    }
  },
  "links": {
    "request": "https://api.maxar.com/ordering/v1/pipelines/imagery/online-ordering/estimate"
  },
  "request_timestamp": "2025-04-14T20:40:09Z",
  "response_timestamp": "2025-04-14T20:40:15Z",
  "request_duration": 6
}

Get order status

Once an order is placed, you can monitor its status or review the details of your order by making the following request with your order ID.

POST 
https://api.maxar.com/ordering/v1/orders/:id

The id was returned in the response body to your order request. It can also be found in your notifications.

Cancel an order

Once an order is placed, you can monitor its status or review the details of your order by making the following request with your order ID.

POST 
https://api.maxar.com/ordering/v1/orders/:id

The id was returned in the response body to your order request. It can also be found in your notifications.

Order output files

The ordered image is delivered in the file structure shown below. The other files contain order and production metadata.

📄 <order-ID>_manifest.json
📄 <order-ID>-request.json
📁 <production-ID>
└── 📄 <order-ID>_01_P001_TIFF.tif

Overview​

Multispectral​

Panchromatic (WV01 only)​

Ordering Online imagery​

Supported requests​

Place an order​

Request URL​

Online Ordering settings​

Example Online Ordering order​

Validate an order request​

Get a usage estimate​

Get order status​

Cancel an order​

Order output files​