Get Started with GBDX APIs

Learn how to use GBDX APIs and services using this quick tutorial.

For this tutorial, we'll use the GBDX Postman client to make API requests. The GBDX Postman Collection features a section called "Getting Started" which accompanies the steps below. Step 2 will explain how to set up Postman.

Table of Contents

Section Description
Step 1: Get your account credentials Learn how to get your account credentials
Step 2: Set up the Postman client Set up the Postman client and import the GBDX environment and collection files
Step 3: Get a token GBDX authentication is token-based. Learn how to get a token that will allow you to make API requests
Step 4: Search the catalog Search the catalog for imagery using the GBDX Catalog V2 API
Step 5: Place an order and check its status Order Worldview imagery if it's not available (Evaluation plan users cannot order imagery)
Step 6: Submit a task and run a workflow Learn how to register a task (evaluation plan users cannot register tasks) and run a workflow
Step 7: Access the output data from a workflow Learn how to access the output of a workflow

Step 1: Get your account credentials

Before we start, you'll need your GBDX username and password to set up your Postman environment variables (step 2). This table explains how to find these values:

Credentials How to locate
GBDX username This is the email address you used to create your GBDX user account. It must be in valid email address format, for example.
GBDX Password The password you set when you activated your account

Step 2: Set up the Postman client

We've created a "Getting Started" Postman collection that exercises the examples in this guide.

Please use the Postman Instructions & Collections tutorial to install Postman, set up the GBDX environment, and download the GBDX Postman collection. (You don't need the GBDX Vector collection for this tutorial).

Step 3: Get a token

To use GBDX APIs, you'll need an access token.

  1. Once you've set up your environment variables in Postman and imported the GBDX collection, select the collection to open it.
  2. Under "Getting Started", select Get user token.
  3. Select "send."

Example response:


    "access_token": "<this is the bearer token>",
    "expires_in": <duration of token in minutes>,
    "token_type": "Bearer",
    "scope": "openid email offline_access",
    "refresh_token": "<this is the refresh token>"

The value for "access_token" is your user token. Copy it to your clipboard (do not include the quotes).

  1. In Postman, add your token to the environment variables.
    • Select "GBDX" in the top right corner of the Postman client.
    • Under "manage environments", click "GBDX."
    • Paste the token value to the "token" key.
    • Select update.

Your token will expire after 7 days (604800 seconds).

Be sure the GBDX environment is selected before running an API call.

Choose "GBDX" from the dropdown menu in the top right corner if it's not selected. If it's not available, you need to download the environment file.

Step 4: Search the GBDX catalog

You can search the GBDX catalog by spatial area, by date range, or by both. Use "types" to search by a single type or multiple types. Use filters to refine your data set.

Let's search for acquisitions in a subsection of San Francisco, collected between March 1, 2015 and March 1, 2016, with cloud cover of less than 10%, and an off-nadir angle of less than 20.

In Postman, find the folder for Catalog V2. Then choose "Cat V2 search by spatial area."

  1. Determine the criteria for your search.
  2. Send a POST request to If you're using the Postman collection, the url is in the request.
  3. Create the search request body. For this exercise, the body is preset in Postman.

For this example, your search request looks like this:


    "searchAreaWkt": "POLYGON ((-122.41189956665039 37.59415685597818, -122.41189956665039 37.64460175855099, -122.34529495239259 37.64460175855099, -122.34529495239259 37.59415685597818, -122.41189956665039 37.59415685597818))",
    "startDate": "2015-03-01T00:00:00.000Z",
    "endDate": "2016-03-01T23:59:59.999Z",
    "filters": ["cloudCover < 10",
        "offNadirAngle < 20"
    "types": ["DigitalGlobeAcquisition"]

The response will be a JSON body that lists each resulting acquisition and its properties. Each acquisition has a catalogID. This is the ID you'll use to place an order in step 5.

Step 5: Place an order and check its status

Place an order

The Ordering API lets you order imagery and check your order's status. To place an order, you'll need a list of one or more acquisition catalog IDs. You can get the catalog IDs from the search executed in the previous step.

  1. Send a POST request to
  2. Include the list of acquisition catalog IDs you want to order in the request.



Note: Evaluation Plan users are limited to ordering 15 DigitalGlobe images over the lifetime of the evaluation account.

  1. This request will return an order ID, and order information about each catalog ID. Save the order_id. You'll use it to check the status of your order.

Example response:


    "order_id": "383193ee-6e05-48ce-b0e2-5bbcd5fc6467",
    "acquisitions": [
            "acquisition_id": "103001004046DC00",
            "state": "submitted",
            "location": "not_delivered"
            "acquisition_id": "1020010030936B00",
            "state": "submitted",
            "location": "not_delivered"
            "acquisition_id": "103001005275AC00",
            "state": "delivered",
            "location": "s3://receiving-dgcs-tdgplatform-com/058636530010_01_003"
            "acquisition_id": "104001000680BA00",
            "state": "submitted",
            "location": "not_delivered"
            "acquisition_id": "1010010012956800",
            "state": "submitted",
            "location": "not_delivered"
            "acquisition_id": "102001003648FC00",
            "state": "submitted",
            "location": "not_delivered"
            "acquisition_id": "10504100106AA800",
            "state": "submitted",
            "location": "not_delivered"

If the image has been delivered to the GBDX catalog, the state will be "delivered" and the S3 receiving bucket location will be displayed. Some tasks require this location as an input.

Check order status

To check the status of your order, send a GET request to<order_id>. Use the order_ID you saved when you placed the order.


The response format will be the same as above. The "state" and "location" will be update.

Step 6: Submit a task and run a workflow

A workflow chains together a series of tasks and runs them in the specified order. Running a workflow means sending a POST request to the workflow endpoint, with the tasks described in a JSON document.

All tasks require inputs.

When a task requires an S3 bucket location as an input, find the location in the Order response. Location will only be displayed when the state = delivered.

For this tutorial, we'll create and run a workflow with one simple task:

  1. Getting_Started: a simple task that only requires "your_name" as an input, and outputs a .txt file.

To create and run a workflow:

  1. View the Getting_Started task definition
    To view the task definition of the Getting_Started task, use the Postman collection to send a GET request to

This is for informational purposes only. You will not change any values in the task definition. Values will be set in the Workflow definition.

  1. Define and run your workflow
    To run a workflow, send a request to the endpoint, with a JSON body that describes the tasks and sets the run order. Workflows run tasks from the first listed to the last.

This workflow example shows the input and output values of the Getting_Started task. You can try this using the Getting Started "run a workflow" request in the GBDX Postman collection.


        "name": "Getting_Started_Workflow",
        "tasks": [
                "name": "show_getting_started",
                "outputs": [
                        "name": "data",
                        "persist": true,
                        "persistLocation": "getting_started_output"
                "inputs": [
                        "name": "your_name",
                        "value": "GBDX U"

                "taskType": "Getting_Started"

How to find your account ID/prefix

GBDX uses your account ID as the prefix for your S3 bucket. The quickest way to find this value is to log into the S3 browser with your GBDX username (email address) and password.

The path with your account ID will look like this: s3://gbd-customer-data/731835da-2059-42de-ad91-03e6e5198fc6/

Use a name that's easy to recognize. You'll use this name to find your output data in the next step.

For example:"name": "getting_started_output",

The "TaskType" must match the name of the task in the task registry.

For example, "Getting_Started" is the task type. This matches the name of the task in the task registry.

Step 7: Access the output data from a workflow

Use the S3 Browser to view the output of the workflow. You can also download a single file.

You'll need your GBDX username and password to log in.
Try the S3 Browser

The S3 browser will show all the files under your S3 bucket and prefix (account ID). Look for the folder with the name you gave here:

Inside this folder, you'll find a txt file called Hello_World.txt. Open the file to see this successful result:

Welcome to GBDX, [your name]!

==> You just completed your first workflow!

What's Next

You've completed the "Getting Started with GBDX APIs" Tutorial.

GBDX Overview