Ordering and Download

Overview

Once you have results returned from a search, the next step in accessing data is ordering and downloading the products. By ordering a product, you are indicating that you intend to pay for access to the product. In cases where the data is free or you have previously ordered a product, you will not be charged. When products are ordered, the Capella system will begin preparing the products for access by ensuring they are available within a cloud storage bucket. Once the order has been prepared, you can submit a request to download the product, which will create signed URLs for the product assets. These signed URLs can be used to download or transfer the product to your environment or to access cloud optimized geotiffs directly from Capella's storage bucket.

Preparing an Order

To prepare an order, you will need to first create an array of the products you would like to order. You will need both the identifier for the product (granuleId) and the identifier for the collection (collectionId) that the product is part of. The identifiers can be found in the properties of each item returned from a search. In the search results, these properties are called id and collection. A properly formatted request body for an order will look like this:

{
    "items": [
        {
          "collectionId": "capella-geo",
          "granuleId": "CAPELLA_C08_SM_GEO_HH_20220624141049_20220624141053"
        }
    ]
}

Reviewing Cost

If you would like to review the cost of an order before you submit, you can use the order review endpoint and request body described above.

POST https://api.capellaspace.com/orders/review

This will return a summary of the total cost of the order as well as the cost of each individual product. This step is optional before placing an order.

Submitting an Order

To submit the order to the system, you will use the orders endpoint and the request body described above.

POST https://api.capellaspace.com/orders

If an order is successfully submitted, a description of the order and the order status will be returned:

{
  "userId": "4a6...",
  "organizationId": "623...",
  "orderDate": "2023-03-28T22:27:55.763Z",
  "expirationDate": "2023-03-28T23:27:55.763Z",
  "orderId": "955...",
  "orderStatus": "completed",
  "items": [
    {
      "collectionId": "capella-geo",
      "granuleId": "CAPELLA_C08_SM_GEO_HH_20220624141049_20220624141053",
      "previouslyOrdered": true,
      "type": "stripmap",
      "collectionDate": "2022-06-25T23:24:39.347Z"
    }
  ]
}

You can see the status of the order in the orderStatus property. Orders that have a status of completed are ready for download. You will need the orderId from the response to prepare the order for download.

Submitting an Order that includes a single image Analytic product

Single image analytic products, such as Vessel Detection, can be created from any archive imagery. To include a Vessel Detection product to an archive imagery order, an additional block is added to the items list in the request body with the productType and a list of the collectIds for which to create the analytic product. This request is sent to the POST /orders API endpoint.

{
    "items": [
        {
          "collectionId": "capella-geo",
          "granuleId": "CAPELLA_C08_SM_GEO_HH_20220624141049_20220624141053"
        },
        {
          "productType": "VS",
          "collectIds": ["e290bca6-8a6c-4a0b-96bf-9174f8b5bccc"]
        }
    ]
}

Note: a GEO image must be specified as part of the analytic order as this is the product used to derive Vessel Detection, and it must be ordered along with vessel detection.

Preparing an Order for Download

Preparing an order for download is simply a matter of assembling a request using the orderId in the following way:

GET https://api.capellaspace.com/orders/{{orderId}}/download

An array of items will be returned, similar to a search result, but the product asset descriptions will now include signed URLs to the assets in Capella's cloud storage bucket in the href fields. You can use the signed URLs to access the product or transfer the product to your environment.

Automated Workflows

A common workflow is to create an automated routine to query the status of recent task requests, identify task requests that are completed, create an order, and download the data for completed tasks. To encourage efficient API usage and reduce call volume, it is recommended to leverage bulk API operations such as the GET tasks/paged endpoint for these workflows, as opposed to looping through a list of task requests and executing status queries by individual Task Request ID.

For example, the following process can efficiently satisfy the workflow described above:

Fetch the 100 latest submitted tasking requests for a specific Organization ID
```
POST tasks/paged?limit=100&page=1&organizationId=<ORGANIZATION_ID>
```
Filter results by searching status history for 'completed' tasks
```
properties.statusHistory.0.code == 'completed'
```
For each 'completed' tasking request
- Order all assets of all STAC items of collects for tasking request
```
POST orders/task/{taskingRequestId}
```
- Create download assets
```
GET orders/{orderId}/download
```
- Download data using presigned URLs provided in the /download response
Repeat the above steps with results from the next page if necessary
```
POST tasks/paged?limit=100&page=2&organizationId=<ORGANIZATION_ID>
```

NOTE: results of GET tasks/paged are sorted by properties.submissionTime which could be used as an early abort criterion (e.g. stop if latest result of page is older than date x.y.z)

Additional Information

For more information on ordering and downloading data, please see the API reference for Data Access.