# API Reference & Specification

Hydrosat's STAC API is available at <https://stac.hydrosat.com/>. You'll need to sign in (authenticate) to access it.

## SpatioTemporal Asset Catalog (STAC) API

This page includes high-level information on the basic features of the API and provides examples for a few methods of working with it.

{% hint style="info" %}
For more details, please review the STAC API specifications provided at <https://github.com/radiantearth/stac-api-spec>.
{% endhint %}

## STAC API Endpoints

<table><thead><tr><th width="350">Request</th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:green;"><code>GET</code></mark> <code>/collections</code></td><td>Return list of available collections</td></tr><tr><td><mark style="color:green;"><code>GET</code></mark> <code>/collections/{collection_id}</code></td><td>Return metadata for a single collection</td></tr><tr><td><mark style="color:green;"><code>GET</code></mark> <code>/collections/{collection_id}/items</code></td><td>Return list of items in the specified collection </td></tr><tr><td><mark style="color:green;"><code>GET</code></mark> <code>/collections/{collection_id}/items/{item_id}</code></td><td>Retrieve a specific item in a specific collection</td></tr><tr><td><mark style="color:green;"><code>POST</code></mark> <code>/search</code></td><td>Search for items using filters (e.g., date, location)</td></tr></tbody></table>

## STAC Catalog Structure

Hydrosat's STAC catalog is organized into four collections.

<table data-header-hidden><thead><tr><th width="162"></th><th></th></tr></thead><tbody><tr><td><strong>Collection Name</strong></td><td><strong>Description</strong></td></tr><tr><td><code>vz-viri-l1a</code></td><td>Level-1A data from the visible and near-infrared sensor (VIRI)</td></tr><tr><td><code>vz-liri-l1a</code></td><td>Level-1A data from the longwave infrared sensor (LIRI)</td></tr><tr><td><code>vz-l1b</code></td><td>Level-1B data: VIRI &#x26; LIRI aligned and resampled to same resolution</td></tr><tr><td><code>vz-l2</code></td><td>Level-2 data: surface reflectance and surface temperature</td></tr></tbody></table>

Each collection contains a series of items representing individual scenes. Within each item, you will find metadata and links to associated imagery.

<figure><img src="/files/hVVSY7MA813wrNeFBolH" alt="" width="375"><figcaption><p>Simplified structure of Hydrosat's STAC catalog. </p></figcaption></figure>

## STAC Query Examples

### pystac-client

We recommend using the `pystac-client` Python library. This library is specifically designed to interact with STAC catalogs and APIs. Complete documentation for this library can be found [here](https://pystac-client.readthedocs.io/en/latest/). More examples with `pystac` are included in our full [how-to guides](/how-to-guides.md).

```python
import pystac
from pystac_client import Client

# Connect to the STAC catalog.
# See our page on authentication for how to set up your headers.
catalog = Client.open('https://stac.hydrosat.com/', headers=headers)

# Search for Level-2 data intersecting San Francisco from April 2025
search = catalog.search(
        collections = ['vz-l2'],
        bbox = [-123.173825, 37.63983, -122.28178, 37.929824],
        datetime = ["2025-04-01T00:00:00Z", ".."]
    )

# Print a list of STAC items returned from the search    
items = list(search.items())
print(items)
```

### curl

The STAC server can also be queried directly from your terminal using `curl`. For example, you can use a POST request to perform a query, specifying the search parameters as JSON-formatted raw data. For more information, please see the curl [docs](https://curl.se/docs/manpage.html).

```sh
curl -X POST \
--header 'Content-Type: application/json' \
--data '{
    "collections": ["vz-l2"],
    "bbox": [-123.173825, 37.63983, -122.28178, 37.929824],
    "datetime": "2025-04-01T00:00:00Z/2024-05-01T00:00:00Z"
}' \
https://stac.hydrosat.com/
```

### QGIS

As of version 3.42.0, QGIS offers native STAC support through the Data Source Manager. This tool has similar capabilities to the existing [QGIS STAC API plugin](https://stacspec.org/en/tutorials/2-intro-to-stac-api-browser-qgis-plugin/) but is slightly easier to configure and use.&#x20;

To work with Hydrosat's STAC API in QGIS, you will need to authenticate by sending your credentials in an authorization header. Please see our [QGIS how-to guide](/how-to-guides/accessing-hydrosat-data-via-stac-api-in-qgis.md) for more details.


---

# Agent Instructions: 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:

```
GET https://satdocs.hydrosat.com/api-reference-and-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.