Catalog¶

Warning

This low-level client has been deprecated in favor of the newer object-oriented Catalog client.

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) – URL for the catalog service. Only change this if you are being asked to use a non-default Descartes Labs catalog. If not set, then descarteslabs.config.get_settings().CATALOG_URL will be used.
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)

Attributes:

`TIMEOUT`
`UPLOAD_NDARRAY_SUPPORTED_DTYPES`

Methods:

`add_band`(product_id, name[, add_namespace, …])	Add a data band to an existing product.
`add_image`(product_id, image_id[, …])	Add an image metadata entry to a product.
`add_product`(product_id, title, description)	Add a product to your catalog.
`change_band`(product_id, name[, add_namespace])	Update a data band of a product.
`change_image`(product_id, image_id[, …])	Update an image metadata entry of a product.
`change_product`(product_id[, add_namespace, …])	Update a product in your catalog.
`get_band`(product_id, name[, add_namespace])	Get a band by name.
`get_image`(product_id, image_id[, add_namespace])	Get a single image catalog entry.
`get_product`(product_id[, add_namespace])	Get a product.
`iter_upload_results`(product_id[, status, …])	Get result information for debugging your uploads.
`namespace_product`(product_id)	Prefix your user namespace to a product id if it isn’t already there.
`own_bands`()	Get bands owned by you.
`own_products`()	Gets products owned by you.
`product_deletion_status`(deletion_task_id)	Get the status of a long running product deletion job.
`remove_band`(product_id, name[, add_namespace])	Remove a band from the catalog.
`remove_image`(product_id, image_id[, …])	Remove a image from the catalog.
`remove_product`(product_id[, add_namespace, …])	Remove a product from the catalog.
`replace_band`(product_id, name[, srcband, …])	Replaces an existing data band with a new document.
`replace_image`(product_id, image_id[, …])	Replace image metadata with a new version.
`replace_product`(product_id, title, description)	Replace a product in your catalog with a new version.
`upload_image`(files, product_id[, metadata, …])	Upload an image for a product you own.
`upload_ndarray`(ndarray, product_id, image_id)	Upload an ndarray with georeferencing information.
`upload_result`(product_id, upload_id)	Get one upload result with the processing logs.
`upload_results`(product_id[, limit, offset, …])	Get result information for debugging your uploads.

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’, ‘mask’, ‘class’, ‘other’] nodata (int) – Pixel value indicating no data available. 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.
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. 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`. 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 (list(str)) – Name of Google Cloud Bucket. Must be public bucket or Descartes Labs user bucket. May be a string or a list of strings equal in length to that of files. 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 (list(str)) – Subdirectory location. Optional, may be a string or a list of strings equal in length to that of files. 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”. extra_properties (dict) – User defined custom properties for this image. Up to 50 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. 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 write 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

See add_band() for additional kwargs.

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. 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

See add_image() for additional kwargs.

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. 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 write 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. 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. 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. 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", "mask", "class", "other"] 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.
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. 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(s). May be a string or a list of strings of length equal to that of files. 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. Optional, may be a string or a list of strings equal in length to that of files. 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. 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). 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".
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.
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",
                       "mask", "class", "other"].
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.

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

See add_band() for additional kwargs.

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. 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

See add_image() for additional kwargs.

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. 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 write 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

See add_image() for additional kwargs.

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']¶