Introduction to the Catalog API

Upload and Manage your data through the Catalog API

If you haven’t already watched the videos on authentication and using Scenes, please do so now as they will help in this demo.

Data Management with Catalog

The Data Management with Catalog guide is located in the guides sub-directory of example_notebooks. We will go through this notebook together to learn how to use the Descartes Labs Catalog for managing your data.


Managing Products

Users often come with some imagery they want to use within the Platform, or they produce an output that they want to save back into the Catalog. In either case, the Catalog API will enable you to add your data to the Platform.

There are three steps to creating a Product in the Catalog (see our in-depth article here).

  1. Create the Product itself by giving it a name and an ID.
  2. Tell the Catalog what kind of data you intend to upload, and how many layers each image has.
  3. Upload your imagery.

Here, we use the Python client to create a Product, set some of its metadata, and save it. You will see this product in the Catalog under “My Products.” Next, we create the bands red, green, and blue as well as an alpha band that will be used to mask out invalid data. Finally, we use the Scenes API to get an image from the Platform.

from descarteslabs.catalog import OverviewResampler
from descarteslabs.scenes import Scene
scene, geoctx = Scene.from_id("landsat:LC08:01:T1:TOAR:meta_LC08_L1TP_163068_20181025_20181025_01_T1_v1")
ndarray, raster_meta = scene.ndarray(
"red green blue alpha",
# return georeferencing info we need to re-upload

image2 = Image(product=product, name="scene2")
image2.acquired = "2012-01-02"
upload2 = image2.upload_ndarray(
# create overviews for 120m and 240m resolution
overviews=[2, 4],


In this case we’re getting a specific Landsat 8 image and we are only downloading the red, green, and blue bands. Finally, we instantiate an Image and use that image’s upload_ndarray method to upload the bands we just retrieved to the bands in the new product. Your product should now show that it has one image, and you can easily open it in Viewer or use the Python client to retrieve it again.