Now with an undersanding of how STAC items and collections work we can look at how to query data. Behind the scenes sat-api queries both collections and items to find matches, so that if you search for
eo:off_nadir=0, it will return all of the Landsat-8 scenes even though
eo:off_nadir doesn't appear in the
items themselves, only in the landsat-8 collection.
Any metadata field that appears in the
collection properties can be queried by providing those as parameters in the form of key=value as shown below.
All scenes from August 2017:
Sentinel-2 collection scenes from August 2017:
Cloud-free Landsat-8 scenes from 2016:
For numeric fields a range of values can be specified by providing the begin and end values separated by a slash.
Landsat-8 scenes from 2016 with 0-20% cloud cover:
All scenes between Dec 31 2017 and Jan 1 2018:
No search term is more important however than the a geospatial query to find data covering a specific area. The core STAC spec allows for searching by providing a bounding box, with more complex 'intersects' query to query against user provided polygons. Sat-api does not currently support the [simpler] bounding box query, but does support the 'intersects' query.
Caveat emptor: Due to the way sat-api does the two pronged search of collections and items, a side effect is that queries fields that are absent from both will match scenes. For example, if a typo occurs in your query like
datetme=2017-08, then that parameter will be ignored but no warning will be issued. This problem will be fixed once we implement validators into the API.