> For the complete documentation index, see [llms.txt](https://satdocs.hydrosat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://satdocs.hydrosat.com/stac-api-reference-and-specification.md).

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

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

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.

{% hint style="warning" %}
Once you’re authenticated, you can browse Hydrosat's STAC items and view thumbnail previews. However, only users who have ordered specific data can download the full COGs for their selected areas.
{% endhint %}

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

<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 radiance data from the visible and near-infrared sensor (VIRI)</td></tr><tr><td><code>vz-liri-l1a</code></td><td>Level-1A radiance data from the longwave infrared thermal sensor (LIRI)</td></tr><tr><td><code>vz-l1b</code></td><td>Level-1B data: top-of-atmosphere reflectance (VIRI) and brightness temperature (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/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/
```