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.

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_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=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)[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_time='2016-01-01',                             end_time="2016-03-01")
>>> total = 0
>>> for f in features:                     total += 1

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

Get metadata of a single image.

Parameters:key (str) – Image identifier.

Example:

>>> from descarteslabs.client.services import Metadata
>>> meta = Metadata().get('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 product.

Parameters:band_id (str) – Band Identifier.
get_bands_by_key(key)[source]

For a given source id, return the available bands.

Parameters:key (str) – A Metadata identifiers.
Returns:A dictionary of band entries and their metadata.
get_by_ids(ids)[source]

Get metadata for multiple images by id. The response contains found images in the order of the given ids. If no image exists for an id, that id is ignored.

Parameters:ids (list(str)) – Image identifiers.
Returns:List of image metadata.
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_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, limit=100, offset=None, dltile=None, sort_field=None, sort_order=None, randomize=None)[source]

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

Parameters:
  • products (list(str)) – Products identifier(s).
  • sat_id (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_time (str) – Desired starting timestamp, in any common format.
  • end_time (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.
  • offset (int) – Number of items to skip.
  • 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_time='2016-07-01',                                  end_time='2016-07-31T23:59:59')
>>> len(ids)
1

>>> ids
['landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1']
keys(products=None, sat_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, limit=100, offset=0, dltile=None, sort_field=None, sort_order='asc', randomize=None)[source]

Search metadata given a spatio-temporal query. All parameters are optional. Results are paged using limit/offset.

Parameters:
  • products (list(str)) – Products identifier(s).
  • sat_id (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_time (str) – Desired starting timestamp, in any common format.
  • end_time (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.
  • offset (int) – Number of items to skip.
  • 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
>>> keys = Metadata().keys(place='north-america_united-states_iowa',                                  products=['landsat:LC08:PRE:TOAR'],                                  start_time='2016-07-01',                                  end_time='2016-07-31T23:59:59')
>>> len(keys)
1

>>> keys
['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_id=None, date='acquired', place=None, geom=None, start_time=None, end_time=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, limit=100, offset=0, 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_id (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_time (str) – Desired starting timestamp, in any common format.
  • end_time (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.
  • offset (int) – Number of items to skip.
  • 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_time='2016-07-01',                                          end_time='2016-07-31T23:59:59')
>>> len(scenes['features'])
1
summary(products=None, sat_id=None, date='acquired', part=None, place=None, geom=None, start_time=None, end_time=None, cloud_fraction=None, cloud_fraction_0=None, fill_fraction=None, q=None, pixels=None, dltile=None)[source]

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

Parameters:
  • products (list(str)) – Product identifier(s).
  • sat_id (list(str)) – Satellite identifier(s). Deprecated
  • 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_time (str) – Desired starting timestamp, in any common format.
  • end_time (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_time='2016-07-06',                     end_time='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.