GBDX

Ordering Course v2

Overview of DigitalGlobe's GBDX Ordering system, version 2.

The GBDX Orders API lets you order imagery by catalog ID and check the status of your order. To place an order, you will POST a set of catalog IDs. The highest available resolution will be ordered. This includes the maximum number of bands, and both "pan" and "multi" resolution when both are available. The result will also include an order status and the S3 bucket location for each acquisition.

Orders V2 Overview

Version 2 of the GBDX ordering system provides big gains in performance, reliability, and ease of use. These improvements include:

  • The ability to place as many orders as you want, as quickly as you want.
  • New factory throttling guarantees we won't overload the DigitalGlobe (DG) factory. This means fewer ordering issues or failures for our customers.
  • No more duplicate orders. If a catalog ID has been ordered once, we won't order it again.
  • Simplified REST API. You'll use a single endpoint to place an order and check order status. API Responses have been simplified so you can quickly find the information you need.

Ordering V2 uses order_ID instead of Sales_Order_Number.

Order Limit

Orders are limited to 100 catalog IDs per order requests.

Duplicates in an Order

If the same catalog ID is requested more than once in the same order request, they will be collapsed into one ID before the order is sent to the factory.

Authentication

All GBDX APIs require a token for authentication. See the Authentication Course for more information.

SWIR imagery

The Ordering V2 API now supports ordering 7.5-meter SWIR acquisitions. If you have a SWIR catalog ID, you can order it.

A SWIR catalog ID has an “A” in the 4th position instead of an “0”.
Standard catalog ID: 104001000FA34F00
SWIR catalog ID: 104A01000FA34F00

Resources:

Resource Definition
Heartbeat Verify the platform is responsive
Orders The resource for placing orders by catalog ID and getting the status of an order.

Place an Order

To place an order, POST a set of catalog IDs to https://geobigdata.io/orders/v2/order

Your request will look like this:

[
    "104001000506EE00",
    "1010010005231400"
]

The response will look like this:

{
  "order_id": "ebffda38-1d6e-4fff-9ae2-aaca94243c45",
  "acquisitions": [
    {
      "acquisition_id": "1010010005231400",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055046034010_01_003"
    },
    {
      "acquisition_id": "104001000506EE00",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055046005010_01_003"
    }
  ]
}
Item Description
order_id The identifier given for the order. You'll use the order ID to check the status of your order.
acquisition_id The identifier for the ordered catalog ID. The response will include a line item for each catalog ID.
state The order status of the catalog ID. See below for valid states and their definitions.
S3 bucket location When you order catalog IDs, the image files are placed in an Amazon Web Services S3 bucket. This is the bucket location.

Keep track of your Order ID and S3 bucket location.

You'll use the order ID to check the status of your order. You'll need the bucket location to access your data. Some tasks require the S3 bucket location as an input.

See the S3 Storage Service Course to learn how to access your AWS bucket.

Order States

Orders can have the following states:

Order Status Description
submitted The order has been submitted to the GBDX platform
ordering The Acquisition IDs are being ordered from the DigitalGlobe (DG) factory
placed The order has been placed with the DG factory
delivered The Acquisition ID has been delivered from the DG factory and is available
failed The order failed.

Get an Order's Status

To get the status of an Order, send a GET request to https://geobigdata.io/orders/v2/order/<order_id>

The order_ID was provided when you placed the order.

For this example, we're looking for status of Order ID ebffda38-1d6e-4fff-9ae2-aaca94243c45. The response will look like this:

{
  "order_id": "ebffda38-1d6e-4fff-9ae2-aaca94243c45",
  "acquisitions": [
    {
      "acquisition_id": "1010010005231400",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055046034010_01_003"
    },
    {
      "acquisition_id": "104001000506EE00",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055046005010_01_003"
    }
  ]
}

Ordering with Callback Notifications

The Ordering with Callbacks API allows users to place an order and get a callback notification when the order has delivered or fails. The user submits an order with a URL in the JSON request. That url will receive the callback notification.

The callback notification is for the entire order.

If you don't need callback notifications, use the Orders V2 API.

Place an order with callback notifications

To place an order with callbacks, a POST request is submitted to:

POST to https://geobigdata.io/orders/v2/ordercb

The request body includes a set of acquisition IDs (CatIDs) and the URL to send the call back to.

Example:

    { 
      "acquisitionIds": [ "CATID1", "CATID2" ],
      "callback": "http://domainname.tld/callbackHandler"
    }

Response Body:

When the order is submitted, the JSON response body will look like this:

    {
      "order_id": "01af5259-64d9-4e16-a161-d6d5e6f3e958",
      "acquisitions": [
        {
          "acquisition_id": "CATID1",
          "state": "submitted"
        },
        {
          "acquisition_id": "CATID2",
          "state": "submitted"
        }
      ],
      "callback": "http://domainname.tld/callbackHandler"
    }

States that trigger a callback notification

These states will deliver a callback notification for the entire order.

  • Delivered
  • Failed
    Keep track of your Order ID. You'll need it to check the order's status before the callback notification is sent.

Get Order Status

To see the status of an order places to the OrderCB API, with the order ID.

Send a GET request to:

GET https://geobigdata.io/orders/v2/ordercb/<order_id>

Example 1: status = submitted

The Response body will like this, with an updated order state.

    {
      "order_id": "01af5259-64d9-4e16-a161-d6d5e6f3e958",
      "acquisitions": [
        {
          "acquisition_id": "CATID1",
          "state": "submitted"
        },
        {
          "acquisition_id": "CATID2",
          "state": "submitted"
        }
      ]
    }

Example 2: Status = "ordering"

    {
      "order_id": "69cbf97a-8f98-46ae-8102-aef4541cb9fd",
      "acquisitions": [
        {
          "acquisition_id": "10111111",
          "state": "ordering"
        },
        {
          "acquisition_id": "1022222",
          "state": "ordering"
        }
      ]
    }

Get the S3 location of an Image

The /orders/v2/location endpoint lets you find the location of a DigitalGlobe acquisition without placing an order. Send a request to this endpoint with the catalog IDs in the query string.

Sample GET Request

https://geobigdata.io/orders/v2/location?acquisitionIds=["CATID1", "CATID2"]

You can list up to 100 catalog IDs in a single query.

Sample JSON Response

The response will look like this:

    {
      "acquisitions": [
        {
          "acquisition_id": "CATID1",
          "state": "delivered",
          "location": "s3://bucket/prefix"
        },
        {
          "acquisition_id": "CATID2",
          "state": "not_found",
          "location": "not_delivered"
        }
      ]
    }

Each catalog ID in the request will be listed in the JSON response body with a "state" and a "location."

Element Description
acquisition-id This is the catalog ID for the image.
state For each catalog ID, a state of either "not_found" or "delivered" will be returned. A state of "not_found" means the catalog ID has not been delivered yet.
location If the acquisition has been delivered, the s3 bucket location will be returned. If it hasn't been delivered, the location will be "not_delivered."

Note: This API endpoint returns the image location and delivery status only. It does not return order information or order status. To see a catalog ID's order status, see Get Order Status v2.

API Reference Materials

Ordering Course v2

Overview of DigitalGlobe's GBDX Ordering system, version 2.