Ordering Migration
This document summarizes concepts and changes needed to migrate reseller orders to the Hub Ordering API.
Most of the field names used for ordering carry over the same name to the new system, but use different casing. Hub requests use snake case, not camel case, so an old field like requestedGsd will most likely named requested_gsd.
Ordering endpoint
Orders should be placed to:
https://api.maxar.com/ordering/v1/pipelines/{namespace}/{name}/order
On October 27 new backend infrastucture will be released and orders should be sent to:
https://api.maxar.com/ordering/v2/pipelines/{namespace}/{name}/order
Line Items are separate orders
The ordering API is not able to process batch orders and does not have a concept similar to "Line Items". Each image must be ordered in its own API call.
Order validation
Orders can be validated by sending the order request to /validate instead of /order. See Validate Order.
Product types to pipelines
A line item order would specify the product type for the order. The product type now is determined by which pipeline you order from. Pipelines also use longer, more readable names for the product types. See the table below.
| Product Type | Pipeline Namespace/Name |
|---|---|
1B | imagery/system-ready |
OR2A | imagery/view-ready-ortho |
2A | imagery/view-ready |
3D | imagery/map-ready |
For more information, see Archive Ordering.
Product settings
Several product options can be set either as top-level order request fields, or in the pipeline settings object.
Tiling
Commercial Hub users are only presented with the 16kx16k tiling option with other options left undocumented. However, if other tiling options have been used in the past, they can be passed in the order's settings section (OR2A, 2A, and 3D only).
Full Extent
If a Hub order does not include an aoi, the full extent of the strip will be processed. The is no isFullExtent setting.
Clip to strip
Hub orders for OR2A, 2A, and 3D products clip to either the provided AOI or the strip extents. 1Bs are delivered in parts. If an AOI is provided, only the intersecting parts are delivered but there is no clipping for 1Bs.
Stereo orders
The stereo setting isStereo maps to a top level setting in the Hub request named is_stereo.
Requested GSD
The GSD setting requestedGsd maps to a top level setting named requested_gsd.
High Definition settings
High Definition is enabled in the pipeline settings object. When ordering High Definition imagery, make sure to include two additional required settings described in the table footnotes here.
"is_high_definition": true,
"requested_gsd": 0.15,
"use_best_gsd": false,
Cloud delivery to output configuration
Cloud delivery is available via the Hub delivery system. Orders can be sent to cloud storage by including one of their output configuration objects.
Note: Permissions are handled differently in Hub delivery. You may need to make changes to your setup to allow Hub delivery.
See the Output Options for more information.
Pass other values using metadata
Hub order requests can store arbitrary key-value metadata in the metadata section. It may be useful to put previously used fields such as customer IDs into this section.
Callback URLS to notifications
The Hub Ordering API has several ways to send progress notifications. One of these is an HTTP callback. Adding this notification to your order will provide similar functionality to the previous statusCallbackLink. The Hub payload sent to the callback is similar - see HTTP Notifications for details.
The main changes in the notification payload include:
- The order ID is the Hub order ID. Metadata about the processing options and product type are generally not included, but can be retrieved from the Ordering API using the order ID.
- Notifications do pass the user's order
metadatasection and as mentioned above can be used to enhance the notification payload with useful fields. - There are no fields for the customer reference or line IDs, as these are not tracked by Hub ordering.
- There is no datetime value included in the notification itself.
- Archive orders don’t have a percent delivered field - the order is only delivered when 100% complete.
- The
statefield is namedstatusand has different values. There is also additional status messaging in the payload.
Reseller block
Reseller orders require an extra reseller information object in the order request payload. The minimum required fields are:
{
"reseller_data":{
"end_use": {
"code":"AGR",
"user_ids":["0MYTCI86F3"],
},
"bill_to_id":"Z73MJB22PR"
}
}
For an example of a complete order, see the annotated example.
End use codes
End use codes are required. See the End Use Code reference in the Tasking section of the documentation. The same values are used in reseller orders.
Values from CAPI
User ID
The user_ids array should have a single ID. This field is equivalent to the sold_to ID returned in the existing CAPI customers request:
https://api.maxar.com/capi/customers?customer_id=C1SYYJ02G4
Pass the customer ID in the above request to find their.
Bill to ID
This value is also included in the customer request shown above in the field bill_to.