> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sat-utils.gitbook.io/sat-api/documentation/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.