API

Places

class descarteslabs.services.Places(url=None, token=None, auth=<descarteslabs.auth.Auth instance>, maxsize=10, ttl=600)
TIMEOUT = (9.5, 360)

Places and statistics service

categories()

Get a list of categories

data(slug, source=None, category=None, metric=None, date=None, placetype='county')

Get all values for a prefix search and point in time

Parameters:
  • slug (str) – Slug identifier (or shape id).
  • source (str) – Source
  • category (str) – Category
  • metric (str) – Metric
  • date (str) – Date
  • placetype (str) – Restrict results to a particular place type.
find(*args, **kwargs)

Find candidate slugs based on full or partial path.

Parameters:
  • path (str) – Candidate underscore-separated slug.
  • placetype – Optional place type for filtering.

Example:

>>> import descarteslabs as dl
>>> from pprint import pprint
>>> results = dl.places.find('morocco')
>>> _ = results[0].pop('bbox')
>>> pprint(results)
[{'id': 85632693,
  'name': 'Morocco',
  'path': 'continent:africa_country:morocco',
  'placetype': 'country',
  'slug': 'africa_morocco'}]
metrics()

Get a list of metrics

placetypes()

Get a list of place types.

return: list
List of placetypes [‘continent’, ‘country’, ‘dependency’, ‘macroregion’, ‘region’,
‘district’, ‘mesoregion’, ‘microregion’, ‘county’, ‘locality’]
prefix(*args, **kwargs)

Get all the places that start with a prefix

Parameters:
  • slug (str) – Slug identifier.
  • output (str) – Desired geometry format (GeoJSON, TopoJSON).
  • placetype (str) – Restrict results to a particular place type.
  • geom (str) – Desired resolution for the geometry (low, medium, high).
Returns:

GeoJSON or TopoJSON FeatureCollection

Example::
>>> import descarteslabs as dl
>>> il_counties = dl.places.prefix('north-america_united-states_illinois', placetype='county')
>>> len(il_counties['features'])
102
random(geom='low', placetype=None)

Get a random location

geom: string
Resolution for the shape [low (default), medium, high]

return: geojson

search(q, limit=10, country=None, region=None, placetype=None)

Search for shapes

Parameters:
  • q (str) – A query string.
  • limit (int) – Max number of matches to return
  • country (str) – Restrict search to a specific country
  • region (str) – Restrict search to a specific region
  • placetype (str) – Restrict search to a specific placetype
Returns:

list of candidates

Example::
>>> import descarteslabs as dl
>>> from pprint import pprint
>>> results = dl.places.search('texas')
>>> pprint(results[0])
{'bbox': [-106.645584, 25.837395, -93.508039, 36.50035],
 'id': 85688753,
 'name': 'Texas',
 'placetype': 'region',
 'slug': 'north-america_united-states_texas'}
shape(*args, **kwargs)

Get the geometry for a specific slug

Parameters:
  • slug – Slug identifier.
  • output (str) – Desired geometry format (GeoJSON).
  • geom (str) – Desired resolution for the geometry (low, medium, high).
Returns:

GeoJSON Feature

Example::
>>> import descarteslabs as dl
>>> from pprint import pprint
>>> kansas = dl.places.shape('north-america_united-states_kansas')
>>> kansas['bbox']
[-102.051744, 36.993016, -94.588658, 40.003078]
>>> kansas['geometry']['type']
'Polygon'
>>> pprint(kansas['properties'])
{'name': 'Kansas',
 'parent_id': 85633793,
 'path': 'continent:north-america_country:united-states_region:kansas',
 'placetype': 'region',
 'slug': 'north-america_united-states_kansas'}
sources()

Get a list of sources

statistics(slug, source=None, category=None, metric=None)

Get a time series for a specific place

Parameters:
  • slug (str) – Slug identifier (or shape id).
  • slug – Slug identifier (or shape id).
  • source (str) – Source
  • category (str) – Category
  • metric (str) – Metric
value(slug, source=None, category=None, metric=None, date=None)

Get point values for a specific place

Parameters:
  • slug (str) – Slug identifier (or shape id).
  • source (list(str)) – Source(s)
  • category (list(str)) – Category(s)
  • metric (list(str)) – Metric(s)
  • date (str) – Date

Metadata

class descarteslabs.services.Metadata(url=None, token=None, auth=<descarteslabs.auth.Auth instance>)

Image Metadata Service

available_products()

Get the list of product identifiers you have access to.

Example::
>>> import descarteslabs as dl
>>> from pprint import pprint
>>> products = dl.metadata.available_products()
>>> pprint(products)
['landsat:LC08:PRE:TOAR']
bands(products=None, limit=None, offset=None, wavelength=None, resolution=None, tags=None, bands=None, **kwargs)

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.
  • wavelenth (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)

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, const_id=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)

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:

>>> import descarteslabs as dl
>>> features = dl.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)

Get metadata of a single image.

Parameters:key (str) – Image identifier.

Example:

>>> import descarteslabs as dl
>>> meta = dl.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)

Get information about a single product.

Parameters:band_id (str) – Band Identifier.
get_bands_by_constellation(const)

For a given constellation id, return the available bands.

Parameters:const (str) – A constellation name/abbreviation.
Returns:A dictionary of band entries and their metadata.
get_bands_by_key(key)

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)

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)

Get information about a single product.

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

Get information about a single product.

Parameters:product_id (str) – Product Identifier.
ids(products=None, const_id=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)

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

Parameters:
  • products (list(str)) – Products identifier(s).
  • const_id (list(str)) – Constellation 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 date and time (inclusive).
  • end_time (str) – Desired ending date and time (inclusive).
  • 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:

>>> import descarteslabs as dl
>>> ids = dl.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, const_id=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)

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

Parameters:
  • products (list(str)) – Products identifier(s).
  • const_id (list(str)) – Constellation 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 date and time (inclusive).
  • end_time (str) – Desired ending date and time (inclusive).
  • 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:

>>> import descarteslabs as dl
>>> keys = dl.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, **kwargs)

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.
search(products=None, const_id=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)

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).
  • const_id (list(str)) – Constellation 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 date and time (inclusive).
  • end_time (str) – Desired ending date and time (inclusive).
  • 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:

>>> import descarteslabs as dl
>>> scenes = dl.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
sources()

Get a list of image sources.

Example::
>>> import descarteslabs as dl
>>> from pprint import pprint
>>> sources = dl.metadata.sources()
>>> pprint(sources)
[{'product': 'landsat:LC08:PRE:TOAR', 'sat_id': 'LANDSAT_8'}]
summary(products=None, const_id=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)

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

Parameters:
  • products (list(str)) – Product identifier(s).
  • const_id (list(str)) – Constellation identifier(s).
  • sat_id (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_time (str) – Desired starting date and time (inclusive).
  • end_time (str) – Desired ending date and time (inclusive).
  • 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:

>>> import descarteslabs as dl
>>> from pprint import  pprint
>>> pprint(dl.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']}
translate(const_id)

Translate a deprecated constellation identifier into a new-style product identifier.

Parameters:const_id (string) – The constellation identifier to translate.

Raster

class descarteslabs.services.Raster(url=None, token=None, auth=<descarteslabs.auth.Auth instance>)
dlkey(key)

Deprecated. See dltile

dlkey_from_latlon(lat, lon, resolution, tilesize, pad)

Deprecated. See dltile_from_latlon

dlkeys_from_shape(resolution, tilesize, pad, shape)

Deprecated. See dltiles_from_shape

dltile(key)

Given a DLTile key, return a DLTile GeoJSON Feature

Parameters:key (str) – A DLTile key that identifies a DLTile
Returns:A DLTile GeoJSON Feature

Example:

>>> import descarteslabs as dl
>>> from pprint import pprint
>>> pprint(dl.raster.dltile("1024:16:15.0:41:-16:324"))
{'geometry': {'coordinates': [[[59.88428127486957, 44.89851158838881],
                               [60.084634558186266, 44.903806716073376],
                               [60.07740397456606, 45.04621255053833],
                               [59.87655568676388, 45.04089121582091],
                               [59.88428127486957, 44.89851158838881]]],
              'type': 'Polygon'},
 'properties': {'cs_code': 'EPSG:32641',
                'key': '1024:16:15.0:41:-16:324',
                'outputBounds': [254000.0, 4976400.0, 269840.0, 4992240.0],
                'pad': 16,
                'resolution': 15.0,
                'ti': -16,
                'tilesize': 1024,
                'tj': 324,
                'zone': 41},
 'type': 'Feature'}
dltile_from_latlon(lat, lon, resolution, tilesize, pad)

Return a DLTile GeoJSON Feature that covers a latitude/longitude

Parameters:
  • lat (float) – Requested latitude
  • lon (float) – Requested longitude
  • resolution (float) – Resolution of DLTile
  • tilesize (int) – Number of valid pixels per DLTile
  • pad (int) – Number of ghost pixels per DLTile (overlap among tiles)
Returns:

A DLTile GeoJSON Feature

Example:

>>> import descarteslabs as dl
>>> from pprint import pprint
>>> pprint(dl.raster.dltile_from_latlon(45, 60, 15.0, 1024, 16))
{'geometry': {'coordinates': [[[59.88428127486957, 44.89851158838881],
                               [60.084634558186266, 44.903806716073376],
                               [60.07740397456606, 45.04621255053833],
                               [59.87655568676388, 45.04089121582091],
                               [59.88428127486957, 44.89851158838881]]],
              'type': 'Polygon'},
'properties': {'cs_code': 'EPSG:32641',
               'key': '1024:16:15.0:41:-16:324',
               'outputBounds': [254000.0, 4976400.0, 269840.0, 4992240.0],
               'pad': 16,
               'resolution': 15.0,
               'ti': -16,
               'tilesize': 1024,
               'tj': 324,
               'zone': 41},
'type': 'Feature'}
dltiles_from_shape(resolution, tilesize, pad, shape)

Return a feature collection of DLTile GeoJSONs that intersect a GeoJSON Geometry shape.

Parameters:
  • resolution (float) – Resolution of DLTile
  • tilesize (int) – Number of valid pixels per DLTile
  • pad (int) – Number of ghost pixels per DLTile (overlap among tiles)
  • shape (str) – A GeoJSON geometry specifying a shape over which to intersect DLTiles.
Returns:

GeoJSON FeatureCollection of intersecting DLTile geometries.

Example:

>>> import descarteslabs as dl
>>> from pprint import pprint
>>> iowa = dl.places.shape("north-america_united-states_iowa")
>>> tiles = dl.raster.dltiles_from_shape(30.0, 2048, 16, iowa)
>>> pprint(tiles['features'][0])
{'geometry': {'coordinates': [[[-96.81264975325391, 41.04520331997488],
                               [-96.07101667769165, 41.02873098011615],
                               [-96.04576296033328, 41.590072611375206],
                               [-96.79377566762062, 41.606871549447824],
                               [-96.81264975325391, 41.04520331997488]]],
              'type': 'Polygon'},
 'properties': {'cs_code': 'EPSG:32614',
                'key': '2048:16:30.0:14:3:74',
                'outputBounds': [683840.0, 4546080.0, 746240.0, 4608480.0],
                'pad': 16,
                'resolution': 30.0,
                'ti': 3,
                'tilesize': 2048,
                'tj': 74,
                'zone': 14},
 'type': 'Feature'}
get_bands_by_constellation(const)

For a given constellation id, return the available bands.

Parameters:const (str) – A constellation name/abbreviation.
Returns:A dictionary of band entries and their metadata.
get_bands_by_key(key)

For a given source id, return the available bands.

Parameters:key (str) – A Metadata identifiers.
Returns:A dictionary of band entries and their metadata.
ndarray(inputs, bands=None, scales=None, data_type=None, srs=None, resolution=None, dimensions=None, cutline=None, place=None, bounds=None, bounds_srs=None, align_pixels=False, resampler=None, order='image', dltile=None, **pass_through_params)

Retrieve a raster as a NumPy array.

Parameters:
  • inputs – List of Metadata identifiers.
  • bands – List of requested bands. If the last item in the list is an alpha band (with data range [0, 1]) it affects rastering of all other bands: When rastering multiple images, they are combined image-by-image only where each respective image’s alpha band is 1 (pixels where the alpha band is not 1 are “transparent” in the overlap between images). If a pixel is fully masked considering all combined alpha bands it will be 0 in all non-alpha bands.
  • scales – List of tuples specifying the scaling to be applied to each band. If no scaling is desired for a band, use None where appropriate. If a tuple contains four elements, the last two will be used as the output range. For example, (0, 10000, 0, 128) would scale the source values 0-10000 to be returned as 0-128 in the output.
  • data_type (str) – Output data type (Byte, UInt8, UInt16, Float32, etc).
  • srs (str) – Output spatial reference system definition understood by GDAL.
  • resolution (float) – Desired resolution in output SRS units. Incompatible with dimensions
  • dimensions (tuple) – Desired output (width, height) in pixels. Incompatible with resolution
  • cutline (str) – A GeoJSON feature or geometry to be used as a cutline.
  • place (str) – A slug identifier to be used as a cutline.
  • bounds (tuple) – (min_x, min_y, max_x, max_y) in target SRS.
  • bounds_srs (str) – Override the coordinate system in which bounds are expressed.
  • align_pixels (bool) – Align pixels to the target coordinate system.
  • resampler (str) – Resampling algorithm to be used during warping (near, bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3).
  • order (str) – Order of the returned array. image returns arrays as (row, column, band) while gdal returns arrays as (band, row, column).
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
raster(inputs, bands=None, scales=None, data_type=None, output_format='GTiff', srs=None, dimensions=None, resolution=None, bounds=None, bounds_srs=None, cutline=None, place=None, align_pixels=False, resampler=None, dltile=None, save=False, outfile_basename=None, **pass_through_params)

Given a list of Metadata identifiers, retrieve a translated and warped mosaic.

Parameters:
  • inputs – List of Metadata identifiers.
  • bands – List of requested bands. If the last item in the list is an alpha band (with data range [0, 1]) it affects rastering of all other bands: When rastering multiple images, they are combined image-by-image only where each respective image’s alpha band is 1 (pixels where the alpha band is not 1 are “transparent” in the overlap between images). If a pixel is fully masked considering all combined alpha bands it will be 0 in all non-alpha bands.
  • scales – List of tuples specifying the scaling to be applied to each band. If no scaling is desired for a band, use None where appropriate. If a tuple contains four elements, the last two will be used as the output range. For example, (0, 10000, 0, 128) would scale the source values 0-10000 to be returned as 0-128 in the output.
  • output_format (str) – Output format (GTiff, PNG, ...).
  • data_type (str) – Output data type (Byte, UInt8, UInt16, Float32, etc).
  • srs (str) – Output spatial reference system definition understood by GDAL.
  • resolution (float) – Desired resolution in output SRS units. Incompatible with dimensions
  • dimensions (tuple) – Desired output (width, height) in pixels. Incompatible with resolution
  • cutline (str) – A GeoJSON feature or geometry to be used as a cutline.
  • place (str) – A slug identifier to be used as a cutline.
  • bounds (tuple) – (min_x, min_y, max_x, max_y) in target SRS.
  • bounds_srs (str) – Override the coordinate system in which bounds are expressed.
  • align_pixels (bool) – Align pixels to the target coordinate system.
  • resampler (str) – Resampling algorithm to be used during warping (near, bilinear, cubic, cubicsplice, lanczos, average, mode, max, min, med, q1, q3).
  • dltile (str) – a dltile key used to specify the resolution, bounds, and srs.
  • save (bool) – Write resulting files to disk. Default: False
  • outfile_basename (str) – If ‘save’ is True, override default filename using this string as a base.

Utilities

descarteslabs.utilities.properties

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

>>> import descarteslabs as dl
>>> from descarteslabs.utilities import properties as p
>>> dl.metadata.search(products=["sentinel-2:L1C"], q=[p.acquired > "2017", p.cloud_fraction < 0.25])
{'bytes': 28174123929918, 'count': 330034, 'products': ['sentinel-2:L1C']}
>>> dl.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']}
>>> dl.metadata.summary(products=['modis:09:CREFL'], q=[p.sat_id == 'Aqua'])
{'bytes': 68425075256895, 'count': 7162652, 'products': ['modis:09:CREFL']}
>>> dl.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.