In this guide, we’ll walk you through creating an archive order using our API. We’ll break down the JSON request into steps and explain each parameter required for ordering archived imagery. We’ll also show you how to fetch item IDs from your archive search results and use them in your order.

​
Overview

Archive ordering lets you purchase imagery from our archives. Unlike tasking orders where you request new captures, archive orders let you select existing imagery by referencing specific STAC Item IDs. This guide explains the key parameters for an archive order and shows you how to structure your JSON request.

Tip:
First, use the Archive Search endpoints to explore and identify the STAC Items you need. Note their item IDs – these are required when creating an archive order.

​
Step-by-Step Breakdown for Archive Ordering

​
Step 1. Global Order Settings

​
dry_run

Set this flag to true to simulate an order without actually processing it. Use false for a live order.

Snippet:

{
  "dry_run": false
}

​
Step 2. Order Items Array

Your archive order is defined within the order_items array. Each order item represents a separate archive order request. To know more about Order Items, read this page.

Snippet:

{
  "order_items": [
    { /* Archive order item details go here */ }
  ]
}

​
Step 3. Configure Archive Order Item Details

​
a. Define the AOI

For archive orders, you need to include an AOI to specify the spatial context of your order. This is required to create an archive order.

  • Field: geometry
  • Format: GeoJSON FeatureCollection

Snippet:

{
  "geometry": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {},
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [<LONGITUDE_1>, <LATITUDE_1>],
              [<LONGITUDE_2>, <LATITUDE_2>],
              [<LONGITUDE_3>, <LATITUDE_3>],
              [<LONGITUDE_4>, <LATITUDE_4>],
              [<LONGITUDE_1>, <LATITUDE_1>]
            ]
          ]
        }
      }
    ]
  }
}

​
b. Specify the Item IDs

Lists the unique identifiers of the STAC Items you wish to order. These IDs are retrieved from the Archive Search results.

  • Field: item_ids
  • Format: An array of strings.
  • Insert the item IDs from your search (e.g., "TD1_005630_20230314_L2A_20230504_03001069").

Snippet:

{
  "item_ids": [
    "<ITEM_ID_1>",
    "<ITEM_ID_2>"
  ]
}

​
c. Order Name

A descriptive name to help you track the order.

  • Field: name
  • Provide a meaningful name (e.g., “Order Archive”).

Snippet:

{
  "name": "Order Archive"
}

​
d. Associate Your Order with a Project

Links the order to a specific project.

  • Field: project_id

Note:
Ensure your service account is added to the project via the UI.

Snippet:

{
  "project_id": "<PROJECT_ID>"
}

​
e. Configure Automatic Delivery (Cloud Config)

If you want the imagery to be automatically delivered to a designated store, you can include cloud configuration details.

  • cloud_delivery Specifies the store configuration for automatic delivery.
  • Provide the store ID (config) and optionally the delivery path (path).

Snippet:

{
  "cloud_delivery": {
    "config": "<STORE_ID>",
    "path": "<DELIVERY_PATH>" // e.g., "/path/to/destination"
  }
}

​
f. Declare the Use Case

Specifies the intended use for the imagery.

  • Field: usecase
  • Action:
    Provide a predefined value (e.g., "agriculture").

Snippet:

{
  "usecase": "<USE_CASE>"
}

​
Putting It All Together

Below is the complete JSON request for an archive order. This request uses the item IDs you fetched from your Archive Search (see the Archive Search Guide above).

{
  "dry_run": false,
  "order_items": [
    {
      "geometry": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "properties": {},
            "geometry": {
              "type": "Polygon",
              "coordinates": [
                [
                  [<LONGITUDE_1>, <LATITUDE_1>],
                  [<LONGITUDE_2>, <LATITUDE_2>],
                  [<LONGITUDE_3>, <LATITUDE_3>],
                  [<LONGITUDE_4>, <LATITUDE_4>],
                  [<LONGITUDE_1>, <LATITUDE_1>]
                ]
              ]
            }
          }
        ]
      },
      "item_ids": [
        "<ITEM_ID_1>",
        "<ITEM_ID_2>"
      ],
      "cloud_delivery": {
        "config": "<STORE_ID>",
        "path": "my-bucket/my-folder"
      },
      "name": "Order Archive",
      "project_id": "<PROJECT_ID>",
      "usecase": "<USE_CASE>"
    }
  ]
}

​
How to Use the Archive Ordering Endpoint

  1. Fetch STAC Item IDs:
    Use our Archive Search endpoints to identify and note the STAC Item IDs of the imagery you wish to order.
  2. Construct Your Request:
    Combine the item IDs with the other required parameters (AOI, project association, use case, etc.) as shown above.
  3. Submit the Order:
    Send the POST request to the Archive Ordering endpoint using your API key in the header:
Authorization: <YOUR_API_KEY>

This guide should help you understand the parameters needed for ordering archives and how to construct your JSON request step by step. For additional details or troubleshooting, please refer to our Archives Documentation.