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

Catalog

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

Product

A raster product that connects band information to imagery.

DeletionTaskStatus

The asynchronous deletion task’s status

UpdatePermissionsTaskStatus

The asynchronous task status for updating related objects’ access control permissions

Bands

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

Image

An image with raster data.

ImageUpload

The status object returned when you upload an image using upload() or upload_ndarray().

Search

Search

A search request that iterates over its search results.

ImageSearch

A search request that iterates over its search results for images.

SummaryResult

The readonly data returned by ImageSearch.summary() or ImageSearch.summary_interval().

properties

A wrapper object to allow constructing filter expressions using properties.

Types

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.

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.

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.

Exceptions

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.