Catalog

class Catalog(url=None, auth=None, metadata=None, retries=None)[source]

The Descartes Labs (DL) Catalog allows you to add georeferenced raster products into the Descartes Labs Platform. Catalog products can be used in other DL services like Raster and Tasks and Metadata.

The entrypoint for using catalog is creating a Product using add_product(). After creating a product you should add band(s) to it using add_band(), and upload imagery using upload_image().

Bands define where and how data is encoded into imagery files, and how it should be displayed. Images define metadata about a specific groups of pixels (in the form of images), their georeferencing, geometry, coordinate system, and other pertinent information.

The parent Service class implements authentication and exponential backoff/retry. Override the url parameter to use a different instance of the backing service.

Parameters:
  • url (str) – A HTTP URL pointing to a version of the storage service (defaults to current version)
  • auth (Auth) – A custom user authentication (defaults to the user authenticated locally by token information on disk or by environment variables)
  • metadata (Metadata) – A custom metadata client to use
  • retries (urllib3.util.retry.Retry) – A custom retry configuration used for all API requests (defaults to a reasonable amount of retries)
add_band(product_id, name, add_namespace=False, srcband=None, dtype=None, data_range=None, type=None, **kwargs)[source]

Add a data band to an existing product.

Parameters:
  • product_id (str) – (Required) Product to which this band will belong.
  • name (str) – (Required) Name of this band.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
  • jpx_layer (int) – If data is processed to JPEG2000, which layer is the band in. Defaults to 0.
  • srcband (int) – (Required) The 1-based index of the band in the jpx_layer specified.
  • srcfile (int) – If the product was processed into multiple files, which one is this in. Defaults to 0 (first file).
  • dtype (str) – (Required) The data type used to store this band e.g Byte or Uint16 or Float32.
  • data_range (list(int)) – (Required) A list specifying the min and max values for the data in this band.
  • type (str) – (Required) The data interpretation of the band. One of [‘spectral’, ‘derived’, ‘mask’, ‘class’]
  • nodata (int) – Pixel value indicating no data available.
  • read (list(str)) – A list of groups, or user hashes to give read access to. Defaults to the same as the parent product if not specified.
  • color (str) – The color interpretation of this band. One of [‘Alpha’, ‘Black’, ‘Blue’, ‘Cyan’, ‘Gray’, ‘Green’, ‘Hue’, ‘Ligntness’, ‘Magenta’, ‘Palette’, ‘Red’, ‘Saturation’, ‘Undefined’, ‘YCbCr_Cb’, ‘YCbCr_Cr’, ‘YCbCr_Y’, ‘Yellow’]. Must be ‘Alpha’ if type is ‘mask’. Must be ‘Palette’ if colormap_name or colormap is set.
  • colormap_name (str) – A named colormap to use for this band, one of [‘plasma’, ‘magma’, ‘viridis’, ‘msw’, ‘inferno’]
  • colormap (list(list(str))) – A custom colormap to use for this band. Takes a list of lists, where each nested list is a 4-tuple of rgba values to map pixels whose value is the index of the tuple. e.g. the colormap [[“100”, “20”, “200”, “255”]] would map pixels whose value is 0 in the original band, to the rgba color vector at colormap[0]. Less than 2^nbits 4-tuples may be provided, and omitted values will default map to black.
  • data_description (str) – Description of band data.
  • physical_range (list(float)) – If band represents a physical value e.g reflectance or radiance what are the possible range of those values.
  • data_unit (str) – Units of the physical range e.g w/sr for radiance
  • data_unit_description (str) – Description of the data unit.
  • default_range (list(int)) – A good default scale for the band to use when rastering for display purposes.
  • description (str) – Description of the band.
  • name_common (str) – Standard name for band
  • name_vendor (str) – What the vendor calls the band eg. B1
  • vendor_order (int) – The index of the band in the vendor’s band tables. Useful for referencing the band to other processing properties like surface reflectance.
  • processing_level (str) – Description of how the band was processed if at all.
  • res_factor (int) – Scaling of this band relative to the native band resolution.
  • resolution (int) – Resolution of this band.
  • resolution_unit (str) – Unit of the resolution, must be either “meters” or “degrees”. Required if resolution is specified.
  • wavelength_center (float) – Center position of wavelength.
  • wavelength_fwhm (float) – Full width at half maximum value of the wavelength spread.
  • wavelength_min (float) – Minimum wavelength this band is sensitive to.
  • wavelength_max (float) – Maximum wavelength this band is sensitive to.
  • wavelength_unit (str) – Units the wavelength is expressed in, must be “nm” if provided.
  • writers (list(str)) – A list of groups, or user hashes to give read access to.
Return type:

dict

Returns:

JSON API representation of the band. See get_band() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • ConflictError – Raised when a band with the specified name already exists.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
add_image(product_id, image_id, add_namespace=False, storage_state='available', **kwargs)[source]

Add an image metadata entry to a product.

Parameters:
  • product_id (str) – (Required) Product to which this image belongs.
  • image_id (str) – (Required) New image’s id = <product_id>:<image_id>.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
  • read (list(str)) – A list of groups, or user hashes to give read access to. Defaults to the same as the parent product if not specified.
  • absolute_orbit (int) – Orbit number since mission start.
  • acquired (str) – Date the imagery was acquired
  • archived (str) – Date the imagery was archived.
  • area (float) – Surface area the image covers
  • azimuth_angle (float) – Satellite azimuth angle in degrees.
  • bits_per_pixel (list(float)) – Average bits of data per pixel per band.
  • bright_fraction (float) – Fraction of the image that has reflectance greater than .4 in the blue band.
  • bucket (str) – Name of Google Cloud Bucket. Must be public bucket or Descartes Labs user bucket.
  • cirrus_fraction (float) – Fraction of pixel which are distorted by cirrus clouds.
  • cloud_fraction (float) – Fraction of pixels which are obscured by clouds.
  • cloud_fraction_0 (float) – Fraction of pixels which are obscured by clouds.
  • cs_code (str) – Spatial coordinate system code eg. EPSG:4326
  • datastrip_id (str) – ID of the data strip this image was taken in.
  • degraded_fraction_0 (float) – Applicable only to Sentinel-2, DEGRADED_MSI_DATA_PERCENTAGE.
  • descartes_version (str) – Processing pipeline version number.
  • directory (str) – Subdirectory location.
  • duration (float) – duration of the scan in seconds
  • earth_sun_distance (float) – Earth sun distance at time of image capture.
  • files (list(str)) – Names of the files this image is stored in.
  • file_md5s (list(str)) – File integrity checksums.
  • file_sizes (list(int)) – Number of bytes of each file
  • fill_fraction (float) – Fraction of this image which has data.
  • or dict geometry (str) – GeoJSON representation of the image coverage.
  • geotrans (float) – Geographic Translator values.
  • identifier (str) – Vendor scene identifier.
  • incidence_angle (float) – Sensor incidence angle.
  • pass (str) – On which pass was this image taken.
  • processed (str) – Date which this image was processed.
  • proj4 (str) – proj.4 transformation parameters
  • projcs (str) – Projection coordinate system.
  • published (str) – Date the image was published.
  • raster_size (list(int)) – Dimensions of image in pixels in (width, height).
  • reflectance_scale (list(float)) – Scale factors converting TOA radiances to TOA reflectances
  • relative_orbit (int) – Orbit number in revisit cycle.
  • roll_angle (float) – Applicable only to Landsat 8, roll angle.
  • safe_id (str) – Standard Archive Format for Europe.
  • sat_id (str) – Satellite identifier.
  • scan_gap_interpolation (float) – Applicable only to Landsat-7, width of pixels interpolated for scan gaps.
  • storage_state (str) – A string indicating whether data for the image is stored on the Descartes Labs platform. Allowed values are “available” and “remote”. If “remote”, entry may not include the fields bucket, directory, files, file_md5s, file_sizes. Default is “available”.
  • writers (list(str)) – A list of groups, or user hashes to give read access to.
  • extra_properties (dict) – User defined custom properties for this image. Only 10 keys are allowed. The dict can only map strings to primitive types (str -> str|float|int).
Return type:

dict

Returns:

JSON API representation of the band. See get_image() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • ConflictError – Raised when a image with the specified ID already exists.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
add_product(product_id, title, description, add_namespace=False, **kwargs)[source]

Add a product to your catalog.

Parameters:
  • product_id (str) – (Required) A unique name for this product. In the created product a namespace consisting of your user id (e.g. “ae60fc891312ggadc94ade8062213b0063335a3c:”) or your organization id (e.g., “yourcompany:”) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
  • read (list(str)) – A list of groups, or user hashes to give read access to.
  • spectral_bands (int) – Number of spectral bands the product has.
  • native_bands (list(str)) – A list of the names of the native bands of this product (most applicable to satellite sensors).
  • start_datetime (str) – ISO-8601 compliant date string, indicating start of product data.
  • end_datetime (str) – ISO-8601 compliant date string, indicating end of product data.
  • notes (str) – Any notes to relay about the product.
  • orbit (str) – Type of orbit (satellite only).
  • processing_level (str) – Way in which raw data has been processed if any.
  • resolution (str) – Pixel density of the data, provide units.
  • revisit (str) – How often an AOI can expect updated data.
  • sensor (str) – Name of the sensor used.
  • swath (str) – How large an area the sensor captures at a given time.
  • writers (list(str)) – A list of groups, or user hashes to give read access to.
Return type:

dict

Returns:

JSON API representation of the product. See get_product() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • ConflictError – Raised when a product with the specified ID already exists.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
change_band(product_id, name, add_namespace=False, **kwargs)[source]

Update a data band of a product.

Parameters:
  • product_id (str) – (Required) Product to which this band belongs.
  • name (str) – Name or id of band to modify.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.

Note

Return type:

dict

Returns:

JSON API representation of the band. See get_band() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • NotFoundError – Raised if the band cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
change_image(product_id, image_id, add_namespace=False, **kwargs)[source]

Update an image metadata entry of a product.

Parameters:
  • product_id (str) – (Required) Product to which this image belongs.
  • image_id (str) – (Required) ID of the image to modify.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.

Note

Return type:

dict

Returns:

JSON API representation of the band. See get_image() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • NotFoundError – Raised if the image cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
change_product(product_id, add_namespace=False, set_global_permissions=False, **kwargs)[source]

Update a product in your catalog.

Parameters:
  • product_id (str) – (Required) The ID of the product to change.
  • read (list(str)) – A list of groups, or user hashes to give read access to.
  • spectral_bands (int) – Number of spectral bands the product has.
  • native_bands (list(str)) – A list of the names of the native bands of this product (most applicable to satellite sensors).
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
  • set_global_permissions (bool) – Update permissions of all existing bands and products that belong to this product with the updated permission set specified in the read param. Default to false.
  • start_datetime (str) – ISO-8601 compliant date string, indicating start of product data.
  • end_datetime (str) – ISO-8601 compliant date string, indicating end of product data.
  • title (str) – Official product title.
  • description (str) – Information about the product, why it exists, and what it provides.
  • notes (str) – Any notes to relay about the product.
  • orbit (str) – Type of orbit (satellite only).
  • processing_level (str) – Way in which raw data has been processed if any.
  • resolution (str) – Pixel density of the data, provide units.
  • revisit (str) – How often an AOI can expect updated data.
  • sensor (str) – Name of the sensor used.
  • swath (str) – How large an area the sensor captures at a given time.
  • writers (list(str)) – A list of groups, or user hashes to give read access to.
Return type:

dict

Returns:

JSON API representation of the product. See get_product() for information about returned keys.

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
get_band(product_id, name, add_namespace=False)[source]

Get a band by name.

Parameters:
  • product_id (str) – ID of the product the band belongs to.
  • name (str) – Name of the band.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
Return type:

dict

Returns:

A single band as a JSON API resource object. The keys are:

data: A dict with the following keys:

    id: The ID of the band.
    type: "band".
    meta: A dict with the following keys:

        modified:   Time that the band was modified
                    in ISO-8601 UTC.
        owner_type: One of ["user", "core"].  "core"
                    bands are owned by Descartes
                    Labs, while "user" bands are
                    owned by individual users.

    attributes: A dict which may contain the following keys:

        color:                 The color interpretation of this
                               band.  One of ["Alpha", "Black",
                               "Blue", "Cyan", "Gray", "Green",
                               "Hue", "Ligntness", "Magenta",
                               "Palette", "Red", "Saturation",
                               "Undefined", "YCbCr_Cb",
                               "YCbCr_Cr", "YCbCr_Y", "Yellow"].

                               "Alpha" if "type" is "mask".
                               "Palette" if "colormap_name" or
                               "colormap" is set.
        colormap:              A custom colormap for this band.
                               A list of lists, where each nested
                               list is a 4-tuple of rgba values
                               to map pixels whose value is the
                               index of the tuple. e.g. the colormap
                               [["100", "20", "200", "255"]] would
                               map pixels whose value is 0 in the
                               original band, to the rgba color
                               vector at colormap[0].  Less than
                               2^nbits 4-tuples may be provided,
                               and omitted values will default
                               map to black.
        colormap_name:         A named colormap for this band,
                               one of ["plasma", "magma",
                               "viridis", "msw", "inferno"]
        data_description:      Description of band data.
        data_range:            A list specifying the min and
                               max values for the data in
                               this band.
        data_unit:             Units of the physical range e.g
                               "w/sr" for radiance.
        data_unit_description: Description of the data unit.
        default_range:         A default scale for the band
                               to use when rastering for
                               display purposes.
        description:           Description of the band.
        dtype:                 The data type used to store this
                               band e.g Byte or Uint16 or Float32.
        jpx_layer:             If data is processed to JPEG2000,
                               which layer is the band in. 0
                               for other formats.
        name:                  Name of the band.
        name_common:           Standard name for band.
        name_vendor:           What the vendor calls the band
                               e.g. B1.
        nbits:                 The number of bits of the dtype
                               used to store this band.
        nodata:                Pixel value indicating no data
                               available.
        owners:                A list of groups, organizations
                               or users who own the product.
                               Access Control List identifiers
                               can have the following formats:
                               organizations, e.g. org:orgname.
                               groups, e.g. group:groupname.
                               user email, e.g. email:user@company.com.
        physical_range:        If band represents a physical
                               value e.g reflectance or
                               radiance what are the possible
                               range of those values.
        processing_level:      Description of how the band was
                               processed if at all.
        product:               ID of the product the band
                               belongs to.
        read:                  A list of groups, organizations
                               or users having read access.
                               Access Control List identifiers
                               can have the following formats:
                               organizations, e.g. org:orgname.
                               groups, e.g. group:groupname.
                               user email, e.g. email:user@company.com.
        res_factor:            Scaling of this band relative to
                               the native band resolution.
        resolution:            Resolution of this band.
        resolution_unit:       Unit of the resolution. One of
                               ["meters", "degrees"].
        src_band:              The 1-based index of the band
                               in the "jpx_layer" specified.
        src_file:              If the product was processed
                               into multiple files, which one
                               is this band in.
        tags:                  A list of searchable tags.
        type:                  The data interpretation of the
                               band. One of ["spectral",
                               "derived", "mask", "class"]
        vendor_order:          The index of the band in the
                               vendor's band tables. Useful
                               for referencing the band to
                               other processing properties
                               like surface reflectance.
        wavelength_center:     Center position of wavelength.
        wavelength_fwhm:       Full width at half maximum value
                               of the wavelength spread.
        wavelength_max:        Maximum wavelength this band
                               is sensitive to.
        wavelength_min:        Minimum wavelength this band
                               is sensitive to.
        wavelength_unit:       Must be "nm" if any wavelength
                               params defined. Otherwise None.
        writers:               A list of groups, organizations
                               or users having write access.
                               Access Control List identifiers
                               can have the following formats:
                               organizations, e.g. org:orgname.
                               groups, e.g. group:groupname.
                               user email, e.g. email:user@company.com.

Raises:
  • NotFoundError – Raised if the band cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
get_image(product_id, image_id, add_namespace=False)[source]

Get a single image catalog entry.

Parameters:
  • product_id (str) – ID of the product the image belongs to.
  • image_id (str) – ID of the image.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
Return type:

dict

Returns:

A single image as a JSON API resource object. The keys are:

data: A dict with the following keys:

   id: The ID of the image.
   type: "image".
   meta: A dict with the following keys:

       modified:   Time that the image was modified
                   in ISO-8601 UTC.
       owner_type: One of ["user", "core"].  "core"
                   images are owned by Descartes Labs,
                   while "user" images are owned by
                   individual users.

   attributes: A dict which may contain the following keys:

       absolute_orbit:         Orbit number since mission start.
       acquired:               Date the imagery was acquired
       archived:               Date the imagery was archived.
       area:                   Surface area the image covers.
       azimuth_angle:          Satellite azimuth angle in degrees.
       bits_per_pixel:         Average bits of data per pixel
                               per band.
       bright_fraction:        Fraction of the image that has
                               reflectance greater than .4 in
                               the blue band.
       bucket:                 Name of Google Cloud Bucket.
       cirrus_fraction:        Fraction of pixel which are
                               distorted by cirrus clouds.
       cloud_fraction:         Fraction of pixels which are
                               obscured by clouds.  Calculated
                               by Descartes Labs.
       cloud_fraction_0:       Fraction of pixels which are
                               obscured by clouds.  Calculated
                               by image provider.
       cs_code:                Spatial coordinate system code
                               eg. "EPSG:4326"
       datastrip_id:           ID of the data strip this image
                               was taken in.
       degraded_fraction_0:    Applicable only to Sentinel-2,
                               DEGRADED_MSI_DATA_PERCENTAGE.
       descartes_version:      Processing pipeline version number.
       directory:              Subdirectory location.
       duration:               Duration of the scan in seconds.
       earth_sun_distance:     Earth sun distance at time of
                               image capture.
       file_md5s:              File integrity checksums.
       file_sizes:             Number of bytes of each file.
       files:                  Names of the files this image
                               is stored in.
       fill_fraction:          Fraction of this image which has
                               data.
       geometry:               GeoJSON representation of the
                               image coverage.
       geotrans:               Geographic Translator values.
       pass:                   On which pass was this image taken.
       identifier:             Vendor scene identifier.
       incidence_angle:        Sensor incidence angle.
       owners:                 A list of groups, organizations
                               or users who own the product.
                               Access Control List identifiers
                               can have the following formats:
                               organizations, e.g. org:orgname.
                               groups, e.g. group:groupname.
                               user email, e.g. email:user@company.com.
       product:                Product to which this image belongs.
       processed:              Date which this image was processed.
       proj4:                  proj.4 transformation parameters.
       projcs:                 Projection coordinate system.
       published:              Date the image was published.
       raster_size:            Dimensions of image in pixels in
                               (width, height).
       read:                   A list of groups, organizations
                               or users having read access.
                               Access Control List identifiers
                               can have the following formats:
                               organizations, e.g. org:orgname.
                               groups, e.g. group:groupname.
                               user email, e.g. email:user@company.com.
       reflectance_scale:      Scale factors converting TOA
                               radiances to TOA reflectances
       relative_orbit:         Orbit number in revisit cycle.
       roll_angle:             Applicable only to Landsat 8,
                               roll angle.
       safe_id:                Standard Archive Format for Europe.
       sat_id:                 Satellite identifier.
       scan_gap_interpolation: Applicable only to Landsat-7,
                               width of pixels interpolated for
                               scan gaps.
       storage_state:          A string indicating whether data
                               for the image is stored on the
                               Descartes Labs platform. Allowed
                               values are "available" and "remote".
                               If "remote", entry may not include
                               the fields bucket, directory,
                               files, file_md5s, file_sizes.
                               Default is "available".
       writers:                A list of groups, organizations
                               or users having write access.
                               Access Control List identifiers
                               can have the following formats:
                               organizations, e.g. org:orgname.
                               groups, e.g. group:groupname.
                               user email, e.g. email:user@company.com.

Raises:
  • NotFoundError – Raised if the image cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
get_product(product_id, add_namespace=False)[source]

Get a product.

Parameters:
  • product_id (str) – ID of the product to get.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
Return type:

dict

Returns:

A single product as a JSON API resource object. The keys are:

data: A dict with the following keys:

    id:   The ID of the product.
    type: "product".
    meta: A dict with the following keys:

        modified:   Time that the product
                    was modified in ISO-8601 UTC.
        owner_type: One of ["user", "core"].
                    "core" products are owned by
                    Descartes Labs, while "user"
                    products are owned by
                    individual users.

    attributes: A dict which may contain
                the following keys:

        description:      Information about the
                          product why it exists,
                          and what it provides.
        end_date:         End date of the product
                          data, None means open interval.
        native_bands:     A list of the names of
                          the native bands of this
                          product (most applicable to
                          satellite sensors).
        notes:            Any notes to relay about
                          the product.
        orbit:            Type of orbit (satellite only).
        owners:           A list of groups, organizations
                          or users who own the product.
                          Access Control List identifiers
                          can have the following formats:
                          organizations, e.g. org:orgname.
                          groups, e.g. group:groupname.
                          user email, e.g.  email:user@company.com.
        processing_level: Way in which raw data has been
                          processed if any.
        read:             A list of groups, organizations
                          or users having read access.
                          Access Control List identifiers
                          can have the following formats:
                          organizations, e.g. org:orgname.
                          groups, e.g. group:groupname.
                          user email, e.g.  email:user@company.com.
        resolution:       Pixel density of the data, provide units.
        revisit:          How often an AOI can expect updated data.
        sensor:           Name of the sensor used.
        spectral_bands:   Number of spectral bands the product has.
        start_date:       Start date of the product data.
        swath:            How large an area the sensor captures
                          at a given time.
        tags:             A list of searchable tags.
        title:            Official product title.
        writers:          A list of groups, organizations
                          or users having write access.
                          Access Control List identifiers
                          can have the following formats:
                          organizations, e.g. org:orgname.
                          groups, e.g. group:groupname.
                          user email, e.g.  email:user@company.com.

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
iter_upload_results(product_id, status=None, updated=None, created=None)[source]

Get result information for debugging your uploads.

Parameters:
  • product_id (str) – Product ID to get upload results for.
  • status (str) – Filter results by status, values are [“SUCCESS”, “FAILURE”]
  • updated (str or int) – Unix timestamp or ISO-8601 formatted date for filtering results updated after this time.
  • created (str or int) – Unix timestamp or ISO-8601 formatted date for filtering results created after this time.
Return type:

generator of dicts

Returns:

An iterator of upload results, with the following keys:

id:         ID of the upload task.
type:       "upload".
attributes: A dict which contains the following keys:

    created:           Time the task was created
                       in ISO-8601 UTC.
    exception_name:    None, or if the task failed
                       the name of the exception raised,
    failure_type:      None, or type of failure if
                       the task failed.  One of
                       ["exception", "oom", "timeout",
                       "internal", "unknown",
                       "py_version_mismatch"].
    peak_memory_usage: Peak memory usage in bytes.
    runtime:           Time in seconds that the task
                       took to complete.
    status:            Status of the task, one of
                       ["SUCCESS", "FAILURE"].

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the status filter has an invalid value.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
namespace_product(product_id)[source]

Prefix your user namespace to a product id if it isn’t already there.

Parameters:product_id (str) – (Required) Id to prefix.
Return type:str
Returns:Namespace prefixed product id.
own_bands()[source]

Get bands owned by you.

Return type:

list[DotDict]

Returns:

A list of band DotDicts which may have the following keys:

color:                 The color interpretation of this
                       band.  One of ["Alpha", "Black",
                       "Blue", "Cyan", "Gray", "Green",
                       "Hue", "Ligntness", "Magenta",
                       "Palette", "Red", "Saturation",
                       "Undefined", "YCbCr_Cb",
                       "YCbCr_Cr", "YCbCr_Y", "Yellow"].

                       "Alpha" if "type" is "mask".
                       "Palette" if "colormap_name" or
                       "colormap" is set.
colormap:              A custom colormap for this band.
                       A list of lists, where each nested
                       list is a 4-tuple of rgba values
                       to map pixels whose value is the
                       index of the tuple. e.g. the
                       colormap [["100", "20", "200", "255"]]
                       would map pixels whose value is 0 in
                       the original band, to the rgba color
                       vector at colormap[0].  Less than
                       2^nbits 4-tuples may be provided,
                       and omitted values will default
                       map to black.
colormap_name:         A named colormap for this band,
                       one of ["plasma", "magma",
                       "viridis", "msw", "inferno"].
data_description:      Description of band data.
data_range:            A list specifying the min and
                       max values for the data in this band.
data_unit:             Units of the physical range e.g
                       "w/sr" for radiance.
data_unit_description: Description of the data unit.
default_range:         A default scale for the
                       band to use when rastering
                       for display purposes.
description:           Description of the band.
dtype:                 The data type used to store
                       this band e.g Byte or
                       Uint16 or Float32.
id:                    The ID of the band.
jpx_layer:             If data is processed to JPEG2000,
                       which layer is the band in. 0
                       for other formats.
modified:              Time that the band was modified
                       in ISO-8601 UTC.
name:                  Name of the band.
name_common:           Standard name for band.
name_vendor:           What the vendor calls the band
                       e.g. B1.
nbits:                 The number of bits of the dtype
                       used to store this band.
nodata:                Pixel value indicating no data
                       available.
owner_type:            One of ["user", "core"].  "core"
                       bands are owned by Descartes Labs,
                       while "user" bands are owned by
                       individual users.
owners:                A list of groups, organizations
                       or users who own the product.
                       Access Control List identifiers
                       can have the following formats:
                       organizations, e.g. org:orgname.
                       groups, e.g. group:groupname.
                       user email, e.g. email:user@company.com.
physical_range:        If band represents a physical
                       value e.g reflectance or
                       radiance what are the possible
                       range of those values.
processing_level:      Description of how the band was
                       processed if at all.
product:               ID of the product the band
                       belongs to.
read:                  A list of groups, organizations
                       or users having read access.
                       Access Control List identifiers
                       can have the following formats:
                       organizations, e.g. org:orgname.
                       groups, e.g. group:groupname.
                       user email, e.g. email:user@company.com.
res_factor:            Scaling of this band relative
                       to the native band resolution.
resolution:            Resolution of this band.
resolution_unit:       Unit of the resolution. One
                       of ["meters", "degrees"].
src_band:              The 1-based index of the band
                       in the "jpx_layer" specified.
src_file:              If the product was processed
                       into multiple files, which one
                       is this band in.
tags:                  A list of searchable tags.
type:                  The data interpretation of
                       the band. One of ["spectral",
                       "derived", "mask", "class"].
vendor_order:          The index of the band in the
                       vendor's band tables. Useful
                       for referencing the band to
                       other processing properties
                       like surface reflectance.
wavelength_center:     Center position of wavelength.
wavelength_fwhm:       Full width at half maximum value
                       of the wavelength spread.
wavelength_max:        Maximum wavelength this band
                       is sensitive to.
wavelength_min:        Minimum wavelength this band
                       is sensitive to.
wavelength_unit:       Must be "nm" if any wavelength
                       params defined. Otherwise None.
writers:               A list of groups, organizations
                       or users having write access.
                       Access Control List identifiers
                       can have the following formats:
                       organizations, e.g. org:orgname.
                       groups, e.g. group:groupname.
                       user email, e.g. email:user@company.com.

Raises:
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
own_products()[source]

Gets products owned by you.

Return type:

list[DotDict]

Returns:

A list of product DotDicts, which may have the following keys:

id:               The ID of the product.
description:      Information about the product
                  why it exists, and what it provides.
title:            Official product title.
modified:         Time that the product was modified
                  in ISO-8601 UTC.
tags:             A list of searchable tags.
owner_type:       One of ["user", "core"].  "core"
                  products are owned by Descartes
                  Labs, while "user" products are
                  owned by individual users.
owners:           A list of groups, organizations
                  or users who own the product.
                  Access Control List identifiers
                  can have the following formats:
                  organizations, e.g. org:orgname.
                  groups, e.g. group:groupname.
                  user email, e.g. email:user@company.com.
read:             A list of groups, organizations
                  or users having read access.
                  Access Control List identifiers
                  can have the following formats:
                  organizations, e.g. org:orgname.
                  groups, e.g. group:groupname.
                  user email, e.g.  email:user@company.com.
writers:          A list of groups, organizations
                  or users having write access.
                  Access Control List identifiers
                  can have the following formats:
                  organizations, e.g. org:orgname.
                  groups, e.g. group:groupname.
                  user email, e.g.  email:user@company.com.
end_date:         End date of the product data,
                  None means open interval.
native_bands:     A list of the names of the native
                  bands of this product (most
                  applicable to satellite sensors).
notes:            Any notes to relay about the product.
orbit:            Type of orbit (satellite only).
processing_level: Way in which raw data has been
                  processed if any.
resolution:       Pixel density of the data, provide units.
revisit:          How often an AOI can expect updated data.
sensor:           Name of the sensor used.
spectral_bands:   Number of spectral bands the product has.
start_date:       Start date of the product data.
swath:            How large an area the sensor
                  captures at a given time.

Raises:
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
product_deletion_status(deletion_task_id)[source]

Get the status of a long running product deletion job.

Parameters:

deletion_task_id (str) – deletion_task ID returned from a call to remove_product() with cascade=True.

Return type:

dict

Returns:

Information about product deletion progress as a dict with the following keys:

completed: Boolean indicating whether
           or not the task is completed.
response:  Information about a completed
           task. A dict with the following keys:

    batches:                Number of batches the operation
                            was broken into.
    created:                Number of products, bands or
                            images created, always 0.
    deleted:                Number of products, bands or
                            images deleted.
    failures:               List of products, bands or
                            images that could not be deleted.
    noops:                  Number of products, bands or
                            images ignored for deletion.
    requests_per_second:    Number of deletion requests
                            executed per second. -1.0 for
                            completed tasks.
    retries:                A dict with the following keys:

        bulk:   Number of product, band or image deletion
                requests retried.
        search: Number of product, band or image search
                requests retried.

    throttled_millis:       Number of milliseconds the
                            request slept to conform to
                            "requests_per_second".
    throttled_until_millis: Always 0.
    timed_out:              Boolean indicating if operations
                            executed timed out.
    took:                   The number of milliseconds from
                            start to end of the whole operation.
    total:                  The number of products, bands and
                            images processed.
    updated:                The number of products, bands and
                            images updated.
    version_conflicts:      The number of products, bands and
                            images that could not be updated
                            due to multiple concurrent updates.

task:      Information about a running task.
           A dict with the following keys:

    batches:                Number of batches the operation
                            was broken into.
    created:                Number of products, bands or
                            images created, always 0.
    deleted:                Number of products, bands or
                            images deleted.
    failures:               List of products, bands or
                            images that could not be deleted.
    noops:                  Number of products, bands or
                            images ignored for deletion.
    requests_per_second:    Number of deletion requests
                            executed per second. -1.0 for
                            completed tasks.
    retries:                A dict with the following keys:

        bulk:   Number of product, band or image deletion
                requests retried.
        search: Number of product, band or image search
                requests retried.

    throttled_millis:       Number of milliseconds the
                            request slept to conform to
                            "requests_per_second".
    throttled_until_millis: Always 0.
    timed_out:              Boolean indicating if operations
                            executed timed out.
    took:                   The number of milliseconds from
                            start to end of the whole operation.
    total:                  The number of products, bands and
                            images processed.
    updated:                The number of products, bands and
                            images updated.
    version_conflicts:      The number of products, bands and
                            images that could not be updated
                            due to multiple concurrent updates.

Raises:
  • NotFoundError – Raised if the task cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
remove_band(product_id, name, add_namespace=False)[source]

Remove a band from the catalog.

Parameters:
  • product_id (str) – ID of the product to remove band from.
  • name (str) – Name of the band to remove.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
Raises:
  • NotFoundError – Raised if the band cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
remove_image(product_id, image_id, add_namespace=False)[source]

Remove a image from the catalog.

Parameters:
  • product_id (str) – ID of the product to remove image from.
  • image_id (str) – ID of the image to remove.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
Raises:
  • NotFoundError – Raised if the product or image cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
remove_product(product_id, add_namespace=False, cascade=False)[source]

Remove a product from the catalog.

Parameters:
  • product_id (str) – ID of the product to remove.
  • cascade (bool) – Force deletion of all the associated bands and images. BEWARE this cannot be undone.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
Return type:

dict or None

Returns:

If called with cascade=False returns None, otherwise returns a dict with the following keys:

deletion_task: Identifier for the task
               that is removing bands and images.

Raises:
  • BadRequestError – Raised when cascade=False and there are dependant bands or images.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
replace_band(product_id, name, srcband=None, dtype=None, data_range=None, add_namespace=False, type=None, **kwargs)[source]

Replaces an existing data band with a new document.

Parameters:
  • product_id (str) – (Required) Product to which this band will belong.
  • name (str) – (Required) Name of this band.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.

Note

Return type:

dict

Returns:

JSON API representation of the band. See get_band() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • NotFoundError – Raised if the band cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
replace_image(product_id, image_id, add_namespace=False, storage_state='available', **kwargs)[source]

Replace image metadata with a new version.

Parameters:
  • product_id (str) – (Required) Product to which this image belongs.
  • image_id (str) – (Required) ID of the image to replace.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
  • storage_state (str) – A string indicating whether data for the image is stored on the Descartes Labs platform. Allowed values are “available” and “remote”. If “remote”, entry may not include the fields bucket, directory, files, file_md5s, file_sizes. Default is “available”.

Note

Return type:

dict

Returns:

JSON API representation of the band. See get_image() for information about returned keys.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • NotFoundError – Raised if the image cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
replace_product(product_id, title, description, add_namespace=False, set_global_permissions=False, **kwargs)[source]

Replace a product in your catalog with a new version.

Parameters:
  • product_id (str) – (Required) A unique name for this product.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.
  • read (list(str)) – A list of groups, or user hashes to give read access to.
  • spectral_bands (int) – Number of spectral bands the product has.
  • native_bands (list(str)) – A list of the names of the native bands of this product (most applicable to satellite sensors).
  • start_datetime (str) – ISO-8601 compliant date string, indicating start of product data.
  • end_datetime (str) – ISO-8601 compliant date string, indicating end of product data.
  • notes (str) – Any notes to relay about the product.
  • orbit (str) – Type of orbit (satellite only).
  • processing_level (str) – Way in which raw data has been processed if any.
  • resolution (str) – Pixel density of the data, provide units.
  • revisit (str) – How often an AOI can expect updated data.
  • sensor (str) – Name of the sensor used.
  • swath (str) – How large an area the sensor captures at a given time.
  • writers (list(str)) – A list of groups, or user hashes to give read access to.
Return type:

dict

Returns:

JSON API representation of the product. See get_product() for information about returned keys.

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
upload_image(files, product_id, metadata=None, multi=False, image_id=None, add_namespace=False, **kwargs)[source]

Upload an image for a product you own.

This is an asynchronous operation and you can query for the status using upload_result() with the upload id returned by this method. The upload id is the image_id, which defaults to the name of the file to be uploaded. The uploaded image can be accessed with Storage using the products storage type. (See the Uploading Data to the Catalog for an example.)

Parameters:
  • files (str or file or list(str) or list(file)) – (Required) a reference to the file to upload.
  • product_id (str) – (Required) The id of the product this image belongs to.
  • metadata (dict) – Image metadata to use instead of the computed default values.
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.

Note

Return type:

str

Returns:

The upload id.

Raises:
  • ValueError – Raised when multi=True but multiple files aren’t provided, or if image_id isn’t specified.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
upload_ndarray(ndarray, product_id, image_id, proj4=None, wkt_srs=None, geotrans=None, raster_meta=None, overviews=None, overview_resampler=None, add_namespace=False, **kwargs)[source]

Upload an ndarray with georeferencing information.

This is an asynchronous operation and you can query for the status using upload_result() with the upload id returned by this method. The upload id is the image_id.

Parameters:
  • ndarray (ndarray) – (Required) A numpy ndarray with image data. If you are providing a multi-band image it should have 3 dimensions and the 3rd dimension of the array should index the bands. The dtype of the ndarray must also be one of the following: [“uint8”, “int8”, “uint16”, “int16”, “uint32”, “int32”, “float32”, “float64”]
  • product_id (str) – (Required) The id of the product this image belongs to.
  • image_id (str) – (Required) Resulting image’s id = <product_id>:<image_id>.
  • proj4 (str) – (One of proj4 or wkt_srs is required) A proj4 formatted string representing the spatial reference system used by the image.
  • wkt_srs (str) – (One of proj4 or wkt_srs is required) A well known text string representing the spatial reference system used by the image.
  • geotrans (list(float)) – (Required) The 6 number geographic transform of the image. Maps pixel coordinates to coordinates in the specified spatial reference system.
  • raster_meta (dict) – Metadata returned from the Raster.ndarray() request which generated the initial data for the ndarray being uploaded. Passing geotrans and wkt_srs is unnecessary in this case.
  • overviews (list(int)) – a list of overview resolution magnification factors e.g. [2, 4] would make two overviews at 2x and 4x the native resolution. Maximum number of overviews allowed is 16.
  • overview_resampler (str) – Resampler algorithm to use when building overviews. Controls how pixels are combined to make lower res pixels in overviews. Allowed resampler algorithms are: [“nearest”, “average”, “gauss”, “cubic”, “cubicspline”, “lanczos”, “average_mp”, “average_magphase”, “mode”].
  • add_namespace (bool) – (Deprecated) Add your user namespace to the product_id.

Note

  • See add_image() for additional kwargs.
  • Only one of proj4 or wkt_srs can be provided.
Return type:

str

Returns:

The upload id.

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
upload_result(product_id, upload_id)[source]

Get one upload result with the processing logs.

This is useful for debugging failed uploads.

Parameters:
  • product_id (str) – Product ID to get upload result for.
  • upload_id (str) – ID of specific upload.
Return type:

dict

Returns:

An single upload result, with the following keys:

id:         ID of the upload task.
type:       "upload".
attributes: A dict which contains the following keys:

    created:           Time the task was created
                       in ISO-8601 UTC.
    exception_name:    None, or if the task failed
                       the name of the exception raised,
    failure_type:      None, or type of failure if
                       the task failed.  One of
                       ["exception", "oom", "timeout",
                       "internal", "unknown",
                       "py_version_mismatch"]
    labels:            List of labels added to the task.
    logs:              Log information output by the task.
    peak_memory_usage: Peak memory usage in bytes.
    runtime:           Time in seconds that the task
                       took to complete.
    stacktrace:        None, or if the task failed,
                       the stacktrace of the exception raised.
    status:            Status of the task, one of
                       ["SUCCESS", "FAILURE"].

Raises:
  • NotFoundError – Raised if the product or upload cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
upload_results(product_id, limit=100, offset=None, status=None, updated=None, created=None, continuation_token=None)[source]

Get result information for debugging your uploads.

Parameters:
  • product_id (str) – Product ID to get upload results for.
  • limit (int) – Number of results to get, useful for paging.
  • offset (int) – Start of results to get, useful for paging.
  • status (str) – Filter results by status, values are [“SUCCESS”, “FAILURE”]
  • updated (str or int) – Unix timestamp or ISO-8601 formatted date for filtering results updated after this time.
  • created (str or int) – Unix timestamp or ISO-8601 formatted date for filtering results created after this time.
Return type:

dict

Returns:

A JSON API representation of the upload results, with the following keys:

data: A list of upload result dicts with the following keys:

    id:         ID of the upload task.
    type:       "upload".
    attributes: A list of dicts which contains the following keys:

        created:           Time the task was created
                           in ISO-8601 UTC.
        exception_name:    None, or if the task failed
                           the name of the exception raised.
        failure_type:      None, or type of failure if
                           the task failed.  One of
                           ["exception", "oom", "timeout",
                           "internal", "unknown",
                           "py_version_mismatch"].
        peak_memory_usage: Peak memory usage in bytes.
        runtime:           Time in seconds that the task
                           took to complete.
        status:            Status of the task, one of
                           ["SUCCESS", "FAILURE"].

meta: A dict with the following keys:

    continuation_token: Token used for paging responses.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the status filter has an invalid value.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
TIMEOUT = (9.5, 30)
UPLOAD_NDARRAY_SUPPORTED_DTYPES = ['uint8', 'int8', 'uint16', 'int16', 'uint32', 'int32', 'float32', 'float64']