GBDX

Get Started with GBDX APIs

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

Last Updated: June 25, 2019

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
Step 6: Submit a task and run a workflow Learn how to register a task 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. youremailaddress@gmail.com
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:

JSON

     {
    "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 //geobigdata.io/catalog/v2/search. 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:

JSON

     {
    "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 //geobigdata.io/orders/v2/order.
  2. Include the list of acquisition catalog IDs you want to order in the request.

JSON

   [
    "103001005275AC00",
    "103001004046DC00",
    "10504100106AA800",
    "1020010030936B00",
    "104001000680BA00",
    "102001003648FC00",
    "1010010012956800"
   ]
  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:

JSON

     {
    "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 GBDX, the state will be "delivered" and the S3 location 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 //geobigdata.io/orders/v2/order/<order_id>`. Use the order_ID you saved when you placed the order.

Example:
//geobigdata.io/orders/v2/order/35a91755-059f-4e14-94a1-b96e05f05fb9

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 a GBDX S3 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//geobigdata.io/workflows/v1/tasks/Getting_Started

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 //geobigdata.io/workflows/v1/workflows 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.

JSON

     {
        "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

The GBDX S3 location is the GBDX S3 bucket name and the Prefix name. GBDX uses your account ID as the prefix. An easy way to find your Account ID is to sign in to https://dashboard.geobigdata.io with your GBDX credentials (email address and password). On the Accounts tab, you'll see Account ID listed under Account Information.

The path with your account ID will look like this: s3://gbd-customer-data//[Account ID]

Use persistLocation to place Output files in the GBDX S3 location

Using the persistLocation property, you can save the output data from a workflow to a specified directory within your GBDX S3 location. Use a name that's easy to recognize.

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

There are several ways to manage the contents stored in a GBDX S3 location. The easiest way is to sign into https://dashboard.geobigdata.io with your GBDX credentials (email address and password, go to the Account tab, and select the "Manage your GBDX S3 contents" button. This will take you to the Amazon S3 Management Console, and will show the files in your GBDX S3 location.

Look for the folder with the name you provided in your Workflow. If you are using the Getting Started example, the folder name will be getting_started_output.

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

Get Started with GBDX APIs


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

Last Updated: June 25, 2019

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.