The Catalog Service provides access to products, bands, and images available from Descartes Labs.


The Catalog API can be found as Python package descarteslabs.catalog. To install please refer to Installation.

Compatibility Warnings

There are a few minor differences from the previous API:

Product ID:
Instead of your Descartes Labs user ID, the product id is now prepended with your Descartes Labs organization ID if available, otherwise it defaults to your Descartes Labs user ID. If the prefix is your Descartes Labs organization ID, it means that your product id must be unique within your organization.
Image and Band Name:
The allowed characters are now a through z, A through Z, 0 through 9, ., _ and -. Note that : is not an allowed character any more.
Image and Band Owners:
The image and band owners will include the owners of the related product. This means that if you’re not the owner of the product (but you are the writer), you can add an image or band and the owners will not only include your Descartes Labs user ID but also the owners of the related product.

The tables below list the objects, types, and exceptions available through the Catalog API. For information on how these objects work together, check out the Catalog Guide.


Product A raster product that connects band information to imagery.
DeletionTaskStatus The asynchronous deletion task’s status


Band A data band in images of a specific product.
SpectralBand A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum.
MicrowaveBand A band that lies in the microwave spectrum, often from SAR or passive radar sensors.
MaskBand A binary band where by convention a 0 means masked and 1 means non-masked.
ClassBand A band that maps a finite set of values that may not be continuous.
GenericBand A generic kind of band not fitting any other type.
DerivedBand A band with pixel values computed from the data in other bands.


Image An image with raster data.
ImageUpload The status object returned when you upload an image using upload() or upload_ndarray().
ImageCollection Holds Images, with methods for loading their data.


Blob A stored blob (arbitrary bytes) that can be searched and retrieved.


Search A search request that iterates over its search results.
ImageSearch A search request that iterates over its search results for images.
ImageSummaryResult The readonly data returned by SummaySearch.summary() or SummaySearch.summary_interval().
BlobSearch A search request that iterates over its search results for blobs.
BlobSummaryResult The readonly data returned by SummaySearch.summary() or SummaySearch.summary_interval().
properties A wrapper object to construct filter properties by referencing instance attributes.


DocumentState The state of the catalog object.
TaskState The state of a task.
DataType Valid data types for bands.
BandType Types of bands with different data interpretation.
Colormap Predefined colormaps available to assign to bands.
ProcessingStepAttribute Processing Levels Step.
ProcessingLevelsAttribute An attribute that contains properties (key/value pairs).
Resolution A spatial pixel resolution with a unit.
ResolutionUnit Valid units of measure for Resolution.
File File definition for an Image.
StorageState The storage state for an image or blob.
StorageType The storage type for a blob.
ImageUploadOptions Control of the upload process.
ImageUploadType The type of upload data.
OverviewResampler Allowed overview resampler algorithms.
ImageUploadStatus The status of the image upload operation.
ImageUploadEvent Image upload event data.
ImageUploadEventType The type of the image upload event.
ImageUploadEventSeverity The severity of an image upload event.


AttributeValidationError There was a problem validating the corresponding attribute.
DeletedObjectError Indicates that an action cannot be performed.
UnsavedObjectError Indicate that an action cannot be performed.

Note that many API calls result in a network request, which can result in a spurious ClientError or ServerError exception. This has been documented for all calls that are susceptible to this. A non-exhaustive list of potential exceptions that can occur are:

  • AuthError when you don’t have the necessary credentials to access the Descartes Labs services.
  • RateLimitError when there are too many request within a given time interval.
  • ServerError when there is an internal error in one of the Descartes Labs services.
  • GatewayTimeoutError when there is congestion in the Descartes Labs networks.

Catalog Client

CatalogClient The CatalogClient handles the HTTP communication with the Descartes Labs catalog.