The Metadata API is a foundational resource for filtering datasets, so scientists and developers can analyze exactly the data they need. The most common interaction you will have with the Metdata API will be searching for available imagery. There are two methods that return subsets of our available imagery: Search and Features.

It is important to note that these methods return image IDs and their associated metadata. To obtain image data for analysis or plotting, you pass the desired IDs to the Raster API. This is a very popular workflow among our users.


Similar to Search, this is the most efficient method for accessing image IDs and their metadata. All parameters are optional. This method is built to handle requests resulting in 10000 returns or more, though it works well for smaller subsets, too. A generator of GeoJSON feature objects is returned, allowing you to efficiently scroll through and access the search results. The input parameters are exactly the same, except no limit is applicable. Instead, a Batch Size may be set to adjust the number of features to fetch per request.

Here’s an example of counting all Landsat 8 TOAR images over the US in our catalog captured in a 6 month period.

import descarteslabs as dl
>>> us = dl.places.find('north-america_united-states')
>>> us_shape = us[0]['slug']
>>> features = dl.metadata.features("landsat:LC08:PRE:TOAR",start_time='2016-01-01',end_time='2016-06-30', place=us_shape)
>>> total = 0
>>> for f in features:
>>>    total += 1
>>> print(There were {} Landsat 8 TOAR images captured over the US from January to June in 2016.".format(total))
There were 8314 Landsat 8 TOAR images captured over the US from January to June in 2016.