# Online Ordering ## Overview[​](#overview "Direct link to Overview") The Online Ordering pipeline offers a streamlined option for ordering satellite imagery. The only required input is the acquisition ID of an image. Online imagery is available for AOIs as small as 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](/docs/analytics/raster/guides/raster-analytics-overview.md#check-if-an-image-is-available-in-the-cloud-optimized-archive-collection) and [Discovery API - Searching Collections](/docs/discovery/guides/VantorCatalogSearchTutorial.md#searching-collections). Online imagery is broadly available for imagery collected since 2024. Older images may be available in high-interest areas. Technical details Online Ordering uses the [Raster Analytics API](/docs/analytics/raster/guides/raster-analytics-overview.md) 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[​](#multispectral "Direct link to Multispectral") ```text function="pansharp_ortho" collect_identifier="" crs="UTM" bands="red,green,blue" dra="true" acomp="false" hd="false" ``` #### Panchromatic (WV01 only)[​](#panchromatic-wv01-only "Direct link to Panchromatic (WV01 only)") ```text function="ortho" collect_identifier="" 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[​](#ordering-online-imagery "Direct link to 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](/docs/ordering/guides/ordering-guide.md). 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[​](#supported-requests "Direct link to Supported requests") Base URL: `https://api.maxar.com` | Request Type | Path | Description | | --------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | [Place an order](/docs/ordering/api/place-order) | `POST /ordering/v2/pipelines/imagery/online-ordering/order` | Places an order to the Online Ordering content pipeline. | | [Validate order](/docs/ordering/api/validate-order) | `POST /ordering/v2/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](/docs/ordering/api/estimate-usage) | `POST /ordering/v2/pipelines/imagery/online-ordering/estimate` | Returns estimated usage for the order. | | [Get the details of an order](/docs/ordering/api/order-details) | `GET /ordering/v2/orders/{id}` | Submit an order ID to view the order's details and status information. | | [Cancel an order](/docs/ordering/api/cancel-order) | `POST /ordering/v2/orders/{id}/cancel` | Submit an order ID to cancel the order before the delivery process begins. | ## Place an order[​](#place-an-order "Direct link to Place an order") ### Request URL[​](#request-url "Direct link to Request URL") An Order request URL requires a "namespace" and a "name. These tell the Ordering API what product to order. ```text POST https://api.maxar.com/ordering/v2/pipelines/{namespace}/{name}/order ``` For Online Ordering, these are: * Namespace: `imagery` * Name: `online-ordering` ```text POST https://api.maxar.com/ordering/v2/pipelines/imagery/online-ordering/order ``` ### Online Ordering settings[​](#online-ordering-settings "Direct link to 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](#example-online-ordering-order). | | customer\_description | optional | Description | `"customer_description": "Project 3"` | > Note: Online Ordering was designed to be a simplified alternative to [Archive Imagery](/docs/ordering/guides/archive-ordering.md) and uses the same parameter names. While Archive 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 ```json { "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[​](#example-online-ordering-order "Direct link to Example Online Ordering order") ```json { "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](/docs/ordering/guides/outputs.md) and [Notifications](/docs/ordering/guides/notifications.md) guides for more information on these sections of the order payload. Example Online Ordering order response ```json { "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/v2/orders/6693768007153061062", "events": "https://api.maxar.com/ordering/v2/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/v2/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[​](#validate-an-order-request "Direct link to Validate an order request") To validate your order before placing it, send your request body to the `/validate` endpoint first. ```text POST https://api.maxar.com/ordering/v2/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` ```json { "data": { "message": "validation successful" }, "links": { "request": "https://api.maxar.com/ordering/v2/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` ```json { "links": { "request": "https://api.maxar.com/ordering/v2/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[​](#get-a-usage-estimate "Direct link to Get a usage estimate") The `/estimate` endpoint returns a usage estimate and a copy of the JSON request body. ```text POST https://api.maxar.com/ordering/v2/pipelines/imagery/online-ordering/estimate ``` Estimate order example 200 response `Status: 200 OK` ```json { "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/v2/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[​](#get-order-status "Direct link to 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. ```text POST https://api.maxar.com/ordering/v2/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[​](#cancel-an-order "Direct link to 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. ```text POST https://api.maxar.com/ordering/v2/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[​](#order-output-files "Direct link to Order output files") The ordered image is delivered in the file structure shown below. The other files contain order and production metadata. ```bash 📄 _manifest.json 📄 -request.json 📁 └── 📄 _01_P001_TIFF.tif ```