API

Places

class descarteslabs.services.Places(url=None, token=None, maxsize=10, ttl=600)
TIMEOUT = (9.5, 120)

Places and statistics service https://iam.descarteslabs.com/service/waldo

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'}]
placetypes()

Get a list of place types.

Example::
>>> import descarteslabs as dl
>>> dl.places.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
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'}

Metadata

class descarteslabs.services.Metadata(url=None, token=None)
TIMEOUT = (9.5, 120)

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)

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, limit=None, offset=None)

Search for predefined derived bands that you have access to.

Parameters:
  • bands (list(str)) – A list of source bands that must be part of the derived band i.e [“nir”]
  • 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, params=None, limit=100, dltile=None, sort_field=None, sort_order='asc')

Generator that combines summary and search to page through results.

Parameters:limit (int) – Number of features to fetch per request.
Returns:Generator of GeoJSON Feature objects.
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_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, params=None, limit=100, offset=0, dltile=None, sort_field=None, sort_order='asc')

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.
  • params (str) – JSON of additional query parameters.
  • 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.
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, params=None, limit=100, offset=0, dltile=None, sort_field=None, sort_order='asc')

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.
  • params (str) – JSON of additional query parameters.
  • 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.
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)

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.
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, params=None, limit=100, offset=0, fields=None, dltile=None, sort_field=None, sort_order='asc')

Search metadata given a spatio-temporal query. All parameters are optional. Results are paged using limit and offset. Please note offset plus limit cannot exceed 10000.

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.
  • params (str) – JSON of additional query parameters.
  • limit (int) – Number of items to return. (max 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.

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, pixels=None, params=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.
  • pixels (bool) – Whether to include pixel counts in summary calculations.
  • params (str) – JSON of additional query parameters.
  • 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)
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)

Retrieve a raster as a NumPy array.

Parameters:
  • inputs – List of Metadata identifiers.
  • bands – List of requested 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)

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

Parameters:
  • inputs – List of Metadata identifiers.
  • bands – List of requested 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.