Metadata

class Metadata(url=None, auth=None)[source]

Image Metadata Service

Any methods that take start and end timestamps accept most common date/time formats as a string. If no explicit timezone is given, the timestamp is assumed to be in UTC. For example '2012-06-01' means June 1st 2012 00:00 in UTC, '2012-06-01 00:00+02:00' means June 1st 2012 00:00 in GMT+2.

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

available_products()[source]

Get the list of product identifiers you have access to.

Example::
>>> from descarteslabs.client.services import Metadata
>>> products = Metadata().available_products()
>>> products  
['landsat:LC08:PRE:TOAR']
bands(products=None, limit=None, offset=None, wavelength=None, resolution=None, tags=None, bands=None, **kwargs)[source]

Search for imagery data bands that you have access to.

Parameters:
  • products (list(str)) – A list of product(s) to return bands for.
  • limit (int) – Number of results to return.
  • offset (int) – Index to start at when returning results.
  • wavelength (float) – A wavelength in nm e.g 700 that the band sensor must measure.
  • resolution (int) – The resolution in meters per pixel e.g 30 of the data available in this band.
  • tags (list(str)) – A list of tags that the band must have in its own tag list.
derived_bands(bands=None, require_bands=None, limit=None, offset=None, **kwargs)[source]

Search for predefined derived bands that you have access to.

Parameters:
  • bands (list(str)) – Limit the derived bands to ones that can be computed using this list of spectral bands. e.g [“red”, “nir”, “swir1”]
  • require_bands (bool) – Control whether searched bands must contain all the spectral bands passed in the bands param. Defaults to False.
  • limit (int) – Number of results to return.
  • offset (int) – Index to start at when returning results.
features(products=None, sat_ids=None, date='acquired', place=None, geom=None, start_datetime=None, end_datetime=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, fields=None, batch_size=1000, dltile=None, sort_field=None, sort_order='asc', randomize=None, **kwargs)[source]

Generator that efficiently scrolls through the search results.

Parameters:batch_size (int) – Number of features to fetch per request.
Returns:Generator of GeoJSON Feature objects.

Example:

>>> from descarteslabs.client.services import Metadata
>>> features = Metadata().features("landsat:LC08:PRE:TOAR",                             start_datetime='2016-01-01',                             end_datetime="2016-03-01")
>>> total = 0
>>> for f in features:                     total += 1

>>> total 
31898
get(image_id)[source]

Get metadata of a single image.

Parameters:image_id (str) – Image identifier.

Example:

>>> from descarteslabs.client.services import Metadata
>>> meta = Metadata().get('landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1')
>>> keys = list(meta.keys())
>>> keys.sort()
>>> keys
['acquired', 'area', 'bits_per_pixel', 'bright_fraction', 'bucket', 'cloud_fraction',
 'cloud_fraction_0', 'cs_code', 'descartes_version', 'file_md5s', 'file_sizes', 'files',
 'fill_fraction', 'geolocation_accuracy', 'geometry', 'geotrans', 'id', 'identifier', 'key',
 'processed', 'product', 'projcs', 'published', 'raster_size', 'reflectance_scale', 'roll_angle',
 'sat_id', 'solar_azimuth_angle', 'solar_elevation_angle', 'sw_version', 'terrain_correction',
 'tile_id']
get_band(band_id)[source]

Get information about a single band.

Parameters:band_id (str) – Band Identifier.
get_bands_by_id(id_)[source]

For a given source id, return the available bands.

Parameters:id (str) – A Metadata identifier.
Returns:A dictionary of band entries and their metadata.
get_bands_by_product(product_id)[source]

All bands (includig derived bands) available in a product.

Parameters:product_id (str) – A product identifier.
Returns:A dictionary mapping band IDs to dictionaries of their metadata.
get_by_ids(ids, fields=None, ignore_not_found=True, **kwargs)[source]

Get metadata for multiple images by id. The response contains found images in the order of the given ids.

Parameters:
  • ids (list(str)) – Image identifiers.
  • fields (list(str)) – Properties to return.
  • ignore_not_found (bool) – For image id lookups that fail: if True, ignore; if False, raise NotFoundError. Default is True.
Returns:

List of image metadata.

Return type:

list(dict)

get_derived_band(derived_band_id)[source]

Get information about a single product.

Parameters:derived_band_id (str) – Derived band identifier.
get_product(product_id)[source]

Get information about a single product.

Parameters:product_id (str) – Product Identifier.
ids(products=None, sat_ids=None, date='acquired', place=None, geom=None, start_datetime=None, end_datetime=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, limit=100, dltile=None, sort_field=None, sort_order=None, randomize=None, **kwargs)[source]

Search metadata given a spatio-temporal query. All parameters are optional.

Parameters:
  • products (list(str)) – Products identifier(s).
  • sat_ids (list(str)) – Satellite identifier(s).
  • date (str) – The date field to use for search (e.g. acquired).
  • place (str) – A slug identifier to be used as a region of interest.
  • geom (str) – A GeoJSON or WKT region of interest.
  • start_datetime (str) – Desired starting timestamp, in any common format.
  • end_datetime (str) – Desired ending timestamp, in any common format.
  • cloud_fraction (float) – Maximum cloud fraction, calculated by data provider.
  • cloud_fraction_0 (float) – Maximum cloud fraction, calculated by cloud mask pixels.
  • fill_fraction (float) – Minimum scene fill fraction, calculated as valid/total pixels.
  • q (expr) – Expression for filtering the results. See descarteslabs.utilities.properties.
  • limit (int) – Number of items to return.
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
  • sort_field (str) – Property to sort on.
  • sort_order (str) – Order of sort.
  • randomize (bool) – Randomize the results. You may also use an int or str as an explicit seed.
Returns:

List of image identifiers.

Example:

>>> from descarteslabs.client.services import Metadata
>>> ids = Metadata().ids(place='north-america_united-states_iowa',                                  products=['landsat:LC08:PRE:TOAR'],                                  start_datetime='2016-07-01',                                  end_datetime='2016-07-31T23:59:59')
>>> len(ids)  
1

>>> ids  
['landsat:LC08:PRE:TOAR:meta_LC80260322016197_v1', 'landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1']
products(bands=None, limit=None, offset=None, owner=None, text=None, **kwargs)[source]

Search products that are available on the platform.

Parameters:
  • bands (list(str)) – Band name(s) e.g [“red”, “nir”] to filter products by. Note that products must match all bands that are passed.
  • limit (int) – Number of results to return.
  • offset (int) – Index to start at when returning results.
  • owner (str) – Filter products by the owner’s uuid.
  • text (str) – Filter products by string match.
search(products=None, sat_ids=None, date='acquired', place=None, geom=None, start_datetime=None, end_datetime=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, limit=100, fields=None, dltile=None, sort_field=None, sort_order='asc', randomize=None, continuation_token=None, **kwargs)[source]

Search metadata given a spatio-temporal query. All parameters are optional. For accessing more than 10000 results, see features().

Parameters:
  • products (list(str)) – Product Identifier(s).
  • sat_ids (list(str)) – Satellite identifier(s).
  • date (str) – The date field to use for search (e.g. acquired).
  • place (str) – A slug identifier to be used as a region of interest.
  • geom (str) – A GeoJSON or WKT region of interest.
  • start_datetime (str) – Desired starting timestamp, in any common format.
  • end_datetime (str) – Desired ending timestamp, in any common format.
  • cloud_fraction (float) – Maximum cloud fraction, calculated by data provider.
  • cloud_fraction_0 (float) – Maximum cloud fraction, calculated by cloud mask pixels.
  • fill_fraction (float) – Minimum scene fill fraction, calculated as valid/total pixels.
  • q (expr) – Expression for filtering the results. See descarteslabs.utilities.properties.
  • limit (int) – Number of items to return up to the maximum of 10000.
  • fields (list(str)) – Properties to return.
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
  • sort_field (str) – Property to sort on.
  • sort_order (str) – Order of sort.
  • randomize (bool) – Randomize the results. You may also use an int or str as an explicit seed.

return: GeoJSON FeatureCollection

Example:

>>> from descarteslabs.client.services import Metadata
>>> scenes = Metadata().search(place='north-america_united-states_iowa',                                          products=['landsat:LC08:PRE:TOAR'],                                          start_datetime='2016-07-01',                                          end_datetime='2016-07-31T23:59:59')
>>> len(scenes['features'])  
2
summary(products=None, sat_ids=None, date='acquired', part=None, place=None, geom=None, start_datetime=None, end_datetime=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, pixels=None, dltile=None, **kwargs)[source]

Get a summary of the results for the specified spatio-temporal query.

Parameters:
  • products (list(str)) – Product identifier(s).
  • sat_ids (list(str)) – Satellite identifier(s).
  • date (str) – The date field to use for search (e.g. acquired).
  • part (str) – Part of the date to aggregate over (e.g. day).
  • place (str) – A slug identifier to be used as a region of interest.
  • geom (str) – A GeoJSON or WKT region of interest.
  • start_datetime (str) – Desired starting timestamp, in any common format.
  • end_datetime (str) – Desired ending timestamp, in any common format.
  • cloud_fraction (float) – Maximum cloud fraction, calculated by data provider.
  • cloud_fraction_0 (float) – Maximum cloud fraction, calculated by cloud mask pixels.
  • fill_fraction (float) – Minimum scene fill fraction, calculated as valid/total pixels.
  • q (expr) – Expression for filtering the results. See descarteslabs.utilities.properties.
  • pixels (bool) – Whether to include pixel counts in summary calculations.
  • dltile (str) – A dltile key used to specify the resolution, bounds, and srs.

Example usage:

>>> from descarteslabs.client.services import Metadata
>>> Metadata().summary(place='north-america_united-states_iowa',                     products=['landsat:LC08:PRE:TOAR'], start_datetime='2016-07-06',                     end_datetime='2016-07-07', part='hour', pixels=True)
{
  'bytes': 93298309,
  'count': 1,
  'items': [
    {
      'bytes': 93298309,
      'count': 1,
      'date': '2016-07-06T16:00:00',
      'pixels': 250508160,
      'timestamp': 1467820800
    }
  ],
  'pixels': 250508160,
  'products': ['landsat:LC08:PRE:TOAR']
}

Filtering

descarteslabs.client.services.metadata.properties

Most of the metadata searching functions allow for flexible filtering on scene metadata.

>>> from descarteslabs.client.services.metadata import Metadata, properties as p
>>> metadata = Metadata()
>>> metadata.search(products=["sentinel-2:L1C"], q=[p.acquired > "2017", p.cloud_fraction < 0.25])
{'bytes': 28174123929918, 'count': 330034, 'products': ['sentinel-2:L1C']}
>>> metadata.summary(products=["sentinel-2:L1C"], q=[p.acquired > "2017", p.cloud_fraction < 0.5, 150 < p.azimuth_angle < 160])
{'bytes': 747678539408, 'count': 5979, 'products': ['sentinel-2:L1C']}
>>> metadata.summary(products=['modis:09:CREFL'], q=[p.sat_id == 'Aqua'])
{'bytes': 68425075256895, 'count': 7162652, 'products': ['modis:09:CREFL']}
>>> metadata.summary(products=['modis:09:CREFL'], q=[p.sat_id == 'Terra'])
{'bytes': 71211948012243, 'count': 7421542, 'products': ['modis:09:CREFL']}
Variables:
  • absolute_orbit

    Number of orbits elapsed since the first ascending node crossing after launch.

    Only present for Sentinel 2 imagery.

  • acquired – Acquisition date and time.
  • archived – Archival date and time.
  • area – Area of the captured scene in square kilometers.
  • azimuth_angle – Satellite azimuth angle in degrees.
  • cirrus_fraction

    Fraction of pixels identified as cirrus clouds. Only applicable to Sentinel-2 data.

    See https://sentinel.esa.int/web/sentinel/technical-guides/sentinel-2-msi/level-1c/cloud-masks for more information.

  • cloud_fraction – Fraction of cloudy pixels determined by the vendor cloud mask.
  • cloud_fraction_0 – Fraction of cloudy pixels supplied by the vendor.
  • earth_sun_distance – Earth-sun distance in astronomical units.
  • geolocation_accuracy – RMSE of the geometric residuals (pixels) in both line and sample directions measured on the terrain-corrected product independently using GLS2000. Only applicable to Landsat data.
  • gsd – Ground sampling distance in meters.
  • opaque_fraction

    Fraction of pixels identified as dense clouds. Only applicable to Sentinel-2 data.

    See https://sentinel.esa.int/web/sentinel/technical-guides/sentinel-2-msi/level-1c/cloud-masks for more information.

  • product – Product identifier (e.g. landsat:LC08:PRE:TOAR)
  • processed – Timestamp of when the scene was processed into the platform.
  • published – Date and time when the scene was published.
  • relative_orbit

    Count of orbits from 1 to the number contained in a repeat cycle. Relative orbit number 1 corresponds to the orbit whose ascending node crossing is closest to the Greenwich Meridian (eastwards).

    Only present for Sentinel 1 and 2 imagery.

  • roll_angle – Satellite zenith angle for Landsat 8 imagery.
  • sat_id – Vendor-specific satellite ID.
  • solar_azimuth_angle – Solar azimuth angle when the scene was captured.
  • solar_elevation_angle – Solar elevation angle when the scene was captured.
  • terrain_correction

    Landsat Level-1 data processing level

    • L1T (Pre-Collection) / L1TP (Collection 1) - Radiometrically calibrated and orthorectified using ground control points and DEM data to correct for relief displacement. These are the highest quality Level-1 products suitable for pixel-level time series analysis.
    • L1GT (Pre-Collection) / L1GT (Collection 1) - Radiometrically calibrated and with systematic geometric corrections applied using the spacecraft ephemeris data and DEM data to correct for relief displacement.
    • L1G (Pre-Collection) / L1GS (Collection 1) - Radiometrically calibrated and with only systematic geometric corrections applied using the spacecraft ephemeris data.

    See https://landsat.usgs.gov/landsat-processing-details/ for more information.

  • tile_id – Vendor-specific tile ID.
  • view_angle – Satellite view angle in degrees.