# STAC API Reference & Specification

Hydrosat's Data Discovery STAC API is available at <https://stac.hydrosat.com/>. The STAC API requires [authentication](/stac-api-reference-and-specification/authentication.md) using a bearer token.

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

Through Hydrosat's STAC API, you can search for data that meets your needs. Data are stored as Cloud-Optimized GeoTIFFs (COGs), which means you can either download the full files or stream only the parts you need using standard web requests.

Learn more:

* STAC (SpatioTemporal Asset Catalog): [stacspec.org](https://stacspec.org)
* Cloud-Optimized GeoTIFFs (COGs): [cogeo.org](https://cogeo.org)

***

While you can use the STAC API directly, we recommend using one of the following tools to make it easier:

* Python library: [pystac-client documentation](https://pystac-client.readthedocs.io/en/stable/)

## STAC API Endpoints

| Request                                          | Description                                       |
|-------------------------------------------------|---------------------------------------------------|
| `GET /collections`                              | Return list of available collections               |
| `GET /collections/{collection_id}`             | Return metadata for a single collection           |
| `GET /collections/{collection_id}/items`      | Return list of items in the specified collection   |
| `GET /collections/{collection_id}/items/{item_id}` | Retrieve a specific item in a specific collection |
| `POST /search`                                  | Search for items using filters (e.g., date, location) |

## STAC Catalog Structure

Hydrosat's STAC catalog is organized into four collections.

| Collection Name         | Description                                                                 |
|-------------------------|-----------------------------------------------------------------------------|
| `vz-viri-l1a`          | Level-1A radiance data from the visible and near-infrared sensor (VIRI)  |
| `vz-liri-l1a`          | Level-1A radiance data from the longwave infrared thermal sensor (LIRI)   |
| `vz-l1b`               | Level-1B data: top-of-atmosphere reflectance (VIRI) and brightness temperature (LIRI) aligned and resampled to same resolution |
| `vz-l2`                | Level-2 data: surface reflectance and surface temperature                   |

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/wwNkxPm8zW9tmokNggxn" alt="" width="563"><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 [Github examples](/stac-api-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 southern Australia from 19 April 2026
search = catalog.search(
        collections = ['vz-l2'],
        bbox = [140.173825, -37.63983, 149.28178, -34.929824],
        datetime = ["2026-01-19T00:00:00Z", "2026-04-19T00: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": [140.173825, -37.63983, 149.28178, -34.929824],
    "datetime": "2026-04-01T00:00:00Z/2025-05-01T00:00:00Z"
}' \
https://stac.hydrosat.com/
```