> For the complete documentation index, see [llms.txt](https://sat-utils.gitbook.io/sat-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sat-utils.gitbook.io/sat-api/documentation/api.md).

# API Docs

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 `items` or `collection` properties can be queried by providing those as parameters in the form of key=value as shown below.

* All scenes from August 2017:   

  <https://sat-api.developmentseed.org/search/stac?datetime=2017-08>
* Sentinel-2 collection scenes from August 2017: &#x20;

  <https://sat-api.developmentseed.org/search/stac?datetime=2017-08&collection=sentinel-2>
* Cloud-free Landsat-8 scenes from 2016: &#x20;

  <https://sat-api.developmentseed.org/search/stac?datetime=2017&collection=landsat-8&eo:cloud_cover=0>

## Range searches

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: &#x20;

  <https://sat-api.developmentseed.org/search/stac?datetime=2017&collection=landsat-8&eo:cloud_cover=0/20>
* All scenes between Dec 31 2017 and Jan 1 2018: &#x20;

  <https://sat-api.developmentseed.org/search/stac?datetime=2016-12-31/2017-01-01>

## Geospatial searches

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.