GBDX Notebooks Course (deprecated)

GBDX Notebooks has been deprecated and will be retired on February 1, 2020. Make a local copy of your notebooks before that date.
Read the deprecation announcement.

Deprecation announced: November 2, 2020
Retirement date: February 1, 2020


Getting Started


To sign in to GBDX Notebooks, these are required:

GBDX credentialsThe GBDX credentials you received when you purchased your GBDX subscription are used to log into GBDX Notebooks.
A Github AccountWe link to your GitHub account so you can publish Gists and share notebooks with groups and organizations that may already exist in your GitHub accounts. You'll only need to link your accounts on your first login.

Sign in to GBDX Notebooks

To sign in to GBDX Notebooks with your account credentials, go to . Click the "Log in" button at the top right of the screen. The login box will appear. Enter your credentials to start the process.

Log in with your GBDX User Account credentials.

Connect your Github Profile

Next, you'll be prompted to connect your GitHub profile. Enter your GitHub credentials to connect your account. If you don't have one, you can create one from this menu.

Connect your GitHub profile to GBDX Notebooks, or create a GitHub profile if you don't have one.

Once you click "connect", your GBDX and GitHub accounts will be connected.

Navigating GBDX Notebooks

GBDX Notebooks is organized into five top level sections. Use the top navigation menu to visit each section.

GBDX Notebooks top navigation menu

My LibrarySelect "My Library" to see the library of notebooks you've created.
DiscoverExplore published notebooks, and clone and edit publicly available Notebooks you want to try.
+New NotebookCreate a new notebook using the "New Notebook" tutorial, or start from a blank notebook.
DocumentationRead the GBDX Notebooks user documentation.

My Library

"My Library" displays the Notebooks you've created. From this page, edit, duplicate, or delete a Notebook.

Filter your view by selecting one of the links to the right of the word "Notebooks".

AllChoose "All" to see your drafts and published notebooks
DraftsChoose "Drafts" to see only your notebooks that have not been published yet.
PublishedChoose "Published" to see only notebooks that you have published.

"My Library" page, with the "All" view selected. This view shows all drafts and published Notebooks.

Notebook Cover Information

The "My Library" page displays a "cover" view of each of your notebooks. Each cover provides basic information about the Notebook, and allows the user to take a series of actions.

NameThe name given to the Notebook by the author
AuthorThe Username of the Notebook's author
PermissionsThe permissions levels are "public" and "private". The default is "public"
Date and TimeThe date and time the Notebook was published
Cover ImageDisplays the image provided by the Notebook's author
TagsThe tags provided by the Notebook's author. These tags are searchable from the "Discover" section. Tags only appear on the cover once the Notebook has been published
DescriptionThe short description provided by the Notebook's author
DraftIf the notebook has not been published, the cover will show "draft", and the description will be "Not published yet."

Notebook Cover Actions

From the Notebook cover, the following actions can be executed:

OpenOpen and edit the content of an existing Notebook.
DeleteDelete the Notebook. This will delete the contents and cover.
DetailsClick "Details" to view the code and output of a Notebook. Metadata can be updated from the details page by clicking the pencil icon next to the name. Notebook content is not editable in this view.



The "Discover" page lets you browse tutorials, search and explore published Notebooks, and clone and edit a public Notebook.

From the Discover page, you can search for, clone, and edit public Notebooks, View Notebook tutorials, and see newly published Notebooks.

Explore Notebooks

The "Explore Notebooks" search feature lets you search for public Notebooks that meet your needs. When you type a word or phrase into the search box, our search engine looks for a full or partial match in the following fields:

  • Name
  • Author name
  • Tags
  • Description

Search results are segmented by "Notebooks" and "People". For example, a search on the term "coast" returns a series of Notebook tutorials with the term "coast" or "coastal" in the title. It also returns a series of Notebooks published by Steve Coast.

Notebooks search results: Notebooks with the phrase "Coast" in the title

People search results: People with "Coast" in their name who have published public notebooks

Notebook Tutorials

The "Notebook Tutorials" section displays collections of tutorials. A collection is a group of tutorials that fall into the same category. Select the collection to view the Notebooks within it.

Notebook tutorials are organized into "collections".

These Notebooks tutorials will walk you through the basics on how to access imagery, and perform various operations against that imagery. The Notebooks are a great way for users to interact with the data with Python, and to learn about the structure and capabilities of DigitalGlobe imagery.

For more information on "gbdxtools", a Python=based tools suite for interacting with GBDX, see gbdxtools documentation.

Newly Published Notebooks

This section displays Notebooks that have been published recently. The newest Notebooks are displayed first.

Search Results

Once a search is executed, the set of Notebook covers that match the search criteria will be returned. Only publicly available Notebooks are returned.

Notebook Covers

Notebook Cover Information

From this view, the Notebook cover shows the following details:

NameThe name given to the Notebook by the author
AuthorThe Username of the Notebook's author. Click on the author's name to see other Notebooks they've authored.
PermissionsOnly Notebooks with permissions set to "public" appear in this view.
Date and TimeThe date and time the Notebook was published.
Cover ImageDisplays the image provided by the Notebook's author.
TagsThe #tags provided by the Notebook's author. These tags are searchable from the "Discover" section.
DescriptionThe short description provided by the Notebook's author.

Notebook Cover Actions

From this view, the following actions can be executed:

DetailsSelect "Details" to view the code and output of a Notebook. Content is not editable in this view.
Clone and EditSelecting the "Clone & Edit" button will create a copy of the Notebook in your own Jupyter Notebook environment. From there you can rename the Notebook, interact with the code, add new code, change the Area of Interest, and more. When you're ready, you can publish the Notebook.

Create a New Notebook

This page lets you create a new Notebook. There are two options available for Notebook creation:

Start with ImageryThis option opens an introductory tutorial with imagery and code samples. This option is ideal for first-time users.Recommended
BlankThis option opens a new Notebook with no code snippets or imagery. To use this option, you'll find imagery by using the AOI selection tool, and create your Python analysis from scratch.Advanced

Change the Python version for a Notebook

When a new Notebook is created, it defaults to Python 3. To update to Python 2 for a new Notebook:

  • Select "kernel"
  • Scroll to the bottom of the kernel menu and select "change kernel."
    *Select "Python 2"

Change the Python version for a new Notebook


The Documentation link brings you back to the documentation you're reading now. You can easily access the GBDX Notebooks course from this link, or from the sidebar navigation on GBDX University.

GBDX Notebooks tutorials are available from within the application. For example, to see the tutorial "Introduction to Image Access with GBDXTools", Choose "New Notebooks", and then "Start with Imagery". Other tutorials can be accessed from the "Discover" page.

Notebook Details Page

View the Notebook details page by clicking the Notebook title or the "Details" button from the Notebook cover. Leave a comment for the Notebook author, or reply to a comment.

View the Notebook Cover Information

At the top of the Notebook details page, you can view the following:

  • Title
  • Publisher
  • Public or Private
  • Cover image
  • Published Date
  • Description
  • Searchable tags

Comment on a Notebook

There are two ways to comment on a Notebook from the Details Page:

  1. Select "Comments" from the top of the Details page

Select the "comments" link from the menu


  1. Scroll to the bottom of the Notebooks Detail Page to see the comments block.

Clone and Edit

The "Clone & Edit" button is available from the top of the Notebook Details Page. This button lets you clone a public Notebook, and then edit the contents of the copy.

Interact with the Code

Select "Code" to see the code used to create the Notebook in "read-only" mode. In this view, you'll see the main description, the section descriptions, the input code blocks, and the output of each section.

View Outputs

Select "Outputs" to see only the outputs of the Notebook. In this view, the code blocks are not displayed.

Creating a New Notebook

To create a new Notebook, select "+New Notebook" from the top navigation bar. You can select one of the following ways to start your new Notebook:

  • Start with Imagery: This option opens an editable tutorial in your Juypter Notebooks environment. The tutorial walks you through selecting imagery and adding code to your Notebook. For first time users, we recommend this option.

  • Blank: This option opens a blank Notebook with no tutorials. You'll use the "imagery" tool on the left sidebar to select imagery.

Once you start to create a new Notebook, you'll notice some differences between your GBDX Notebook and a standard Jupyter Notebook. While the default Notebook behavior is as standardized as possible, we've made changes to streamline your access to DigitalGlobe's imagery catalog.

GBDX Notebooks Custom Toolbar

The custom GBDX Notebooks toolbar will be displayed on the left side of the page. The toolbar offers the following options:

GBDX Notebooks custom toolbar

Tool or LinkDescription
ImageryThe "imagery" icon opens the Area of Interest selection tool. Use this tool to search for imagery and create and save an Area of Interest.
DeployNotebooks can be deployed as "tasks". The "Deploy" icon opens a form page where you'll input your task information and add your input and output requirements. From here, select "Publish" to deploy the task.
OrdersThe "Orders" icon shows the status of imagery orders. Once an order is complete, you have the option to "insert" the image right from the status box.

Select an Area of Interest (AOI)

Select the "Imagery" icon from the sidebar to open the AOI selection tool.

GBDX Notebooks are designed to give access to small AOIs for users to build their methods and algorithms against. The AOI selection tool is zoom-level dependent. The red bar at the bottom of the map lets you know the AOI you've selected is too large. Keep zooming in until the bar turns green. Once the bar turns green, the text will say "Draw a rectangle to select an area of interest."

Narrow your Search Area

To start a search, we recommend typing a location in the search box. It can be a general area, such as "Denver" or a more specific area such as Denver International Airport, Denver, CO. Be as specific as possible to narrow your search.

To zoom in or out to change your AOI, you can:

  • Use the +(plus) button to zoom in, or the -(minus) button to zoom out.
  • Double click the left mouse button to zoom in.
  • Scroll your mouse wheel down to zoom in, and up to zoom out.

In this example, the AOI is too large to allow imagery selection. The user will need to continue to zoom in to a smaller area. When the area is small enough, the zoom bar will turn green.

Select an AOI

Once you have zoomed in to a small enough area, draw a polygon around the specific area to create an AOI. There are two ways to draw a polygon:

  • Select the polygon icon, then click the starting location for your area. Draw and connect each side of your polygon.

  • Select the square icon. Click the start location for the square, then drag to create the boundaries.

Once an area has been selected, the bounding box is shown in the green bar.

Once you select an AOI, the search button at the bottom of the screen will be enabled. Select this button to execute a search. You can set search filters to narrow your results.

Apply Filters

To set search filters before executing a search, click "Search Filters" in the lower left corner of the pane.

When a search is executed, the search results pane is displayed. A horizontal scrolling selector is displayed for each filter. Once the filters are set, select the "search" button to execute the search.

Drag the control to the left or the right to change the filter values.

AOI Search Results

When a search is executed, the image count is displayed at the top of the screen, and the results display at the bottom of the pane.

There are 46 images in this results set.

To narrow the results set further, choose "Additional Filters" in the top left corner of the pane. This brings up the filter box, and the filters can be changed using the horizontal scroll bar.

Imagery Sets for GBDX Notebooks

GBDX Notebooks have access to imagery from the following sensor platforms:


Search Results View

The Search Results view displays the following for each record:

CheckboxClick to check the box next to a record. Clicking the box activates the "insert code" button in the lower right corner.
DateThe date the image was acquired by the satellite.
CoverageEach record is part of the specific AOI you defined; not part of a full image strip. Coverage shows how much overlap exists between your AOI and the strip. 100% means that the image covers the entire AOI you selected.
SourceThe source is the satellite that acquired the image.
CloudsThe percentage of cloud cover in the image. This will help you determine if the image will be useful or not.
PreviewPreview lets you view the image before adding it to your Notebook.
InsertSelecting "Insert" adds the image request code to your Notebook, and fetches the image for preview.
OrderSome images are not available for immediate use, and need to be ordered. Click "Order" to begin the process. See Order an image for more information.

Preview an Image

Selecting "Preview" displays the image and its metadata. If you need to find the catalog ID for an image, it's listed in this view.

The preview pane shows the select image and its associated metadata.

Order an Image

To add an image to a Notebook, the image must be available. Some images are not immediately available and need to be ordered from the DG factory.

  • If an image is available for immediate use, the link at the end of the row will say "insert."

  • If an image is not available for immediate use, it will to be ordered. The link at the end of the row will say "Order."


Your account will be charged when you order an image. Once an order is placed, it cannot be canceled.

This search results set includes images that are available to insert into a Notebook, and an image that needs to be ordered. Clicking "Order" will start the order fulfillment process.

When you click "order" from the search result, a pop up message will warn you that:

  • Your account will be charged for the ordered image
  • The order cannot be canceled once the user hits "continue"
  • Order fulfillment can take several hours

To complete the order, hit "continue."

Check the Status of an Order

Order fulfillment can take several hours. To check the status of an order, click "Orders" in the custom toolbar. The list will show pending and completed orders.

Clicking "Orders" brings up a list of ordered images and their status.

Order submittedThe order has been been placed, but fulfillment hasn't started yet.
Order processingThe image order has been placed to the factory, but has not been delivered yet.
Order completeThe ordered image has been delivered, and is now available to insert into a Notebook.

When an Order is "complete", you have the option to insert it into your Notebook from the order status box. In the search results list, the link that said "order" will now say "insert."

Selecting the "trash" icon removes the line item from the order status box. It does not cancel the order or delete the image.

Insert a Single Image

Once you find an image you want to add to your Notebook for processing, click "insert" from the individual record in the search results, or in the preview pane. This will insert the cell for importing the image into the Notebook, and fetch the image. The cell gives key information about the image, and lets you begin analyzing the imagery. From this cell, you can find the catalog ID and bounding box. It has also plotted the multispectral band for the image.

Many published and publicly available Notebooks have a cell like this as the first cell in the Notebook. You can insert your own cell into the Notebook. This will allow the Notebook to work on the AOI you've selected instead of the AOI included by the original author.

Insert Code for Multiple Images

To insert multiple images at once, click the check box next to each image you want to insert. This will activate the "Insert Code for [number] Images" button.

When you insert code for multiple images at once, the result is a code snippet containing a JSON file. The JSON file contains pointers to all the images you selected.

Using multiple images can be necessary when working with time series, working with change detection, creating mosaics, or anything else you can come up with. For more details on using the notebooks, and interacting with DigitalGlobe imagery you can access our Notebook tutorials, which will walk you through other common operations such as working with the various imagery bands, reprojecting the images, and viewing the full metadata.

GBDX Notebook Tutorials

The GBDX Notebooks Tutorials are the best way to learn how to add capabilities to your Notebook with Python.

This is an example of a GBDX Notebooks tutorial.

Tutorial Notebooks can be cloned, and then edited for your own use.

Publishing a Notebook

Publishing your Notebook allows you to share it with the community or with other users privately. Once a Notebook is published, it appears in the list on the "Discover" page.

Once your Notebook is ready to be shared, click the "Publish Notebook" button.

Click "Publish Notebook" to make your Notebook available for sharing.

Privacy and Sharing

Private and Public Notebooks

When a Notebook is published, it can be set to "private" or "public". "Public" Notebooks are viewable to all users from the "Discover" page. "Private" Notebooks can be set to be available only to you, or to a GitHub organization or group.

Change Permissions Settings on a Notebook

Permissions can only be set on Notebooks that have been published. The default permissions setting is "Public".

To change the permissions settings for a Notebook, do the following:

  1. From "My "Library", find the Notebook you want to update
  2. Click the "Details" button on the Notebook cover (if the task has not been published yet, the "details" button will not appear).
  3. From the "details" page, click the pencil icon next to the name. This will bring up a dialog box.

Click the pencil icon next to the name to update Notebook metadata and change the privacy settings.

  1. From this dialog box, you can update the Notebook's metadata, "unpublish" the Notebook, or change Permissions. Select "Permissions" to change the setting.

Select "Permissions" to change the setting from public to private, and to share the Notebook with a group or organization.

  1. From the "Global Permissions" page, select "Public" or "Private". If you select "Private", additional "Private" settings will be enabled.

  2. To keep the Notebook private to you only, no other selections need to be made.

  3. To keep the Notebook private, but share with your GitHub organization or group, choose the edit buttons and make a selection from the available options.

  1. Once you've added or updated the metadata and privacy settings, select "publish" in the bottom right corner.

Click "publish" to publish the metadata that accompanies your Notebook.

Cancel Publishing

You can cancel publishing by clicking the "Cancel Publishing" button on page shown above. This button only appears when the Notebook has already been published.

Publish Notebook as a gist

Our hosted Notebooks have integrated access to publishing your Notebook as a gist. Click on the small arrow next to the ‘CellToolbar’ to automatically publish the Notebook you’re currently working in as a Gist, which can be accessed through your GitHub account.

Jupyter Notebooks

To learn more about Jupyter Notebooks, see Jupyter Documentation

Feedback and Support

To report an issue or give feedback on GBDX Notebooks, click the "feedback" link on the right side of the window and fill out the feedback form.

Updated 2 months ago

GBDX Notebooks Course (deprecated)

GBDX Notebooks has been deprecated and will be retired on February 1, 2020. Make a local copy of your notebooks before that date.
Read the deprecation announcement.

Deprecation announced: November 2, 2020
Retirement date: February 1, 2020

Suggested Edits are limited on API Reference Pages

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