API Reference and Specification

API Reference and Specification#

The STAC API is available at https://fusion-stac.hydrosat.com/. It supports both unauthenticated and authenticated access.

Spatiotemporal Asset Catalog API#

The STAC API is described in more detail at radiantearth/stac-api-spec. This page provides information on the basic features of the API and will provide examples for two methods of working with the API: curl and pystac-client.

curl#

The STAC server can be queried directly from your terminal using curl (https://curl.se/docs/manpage.html ). For example, you can use a POST request to perform a query, passing the search parameters in as JSON-formatted raw data. In the examples on this page, you will need to replace the YOUR_TOKEN_HERE string with your API token.

pystac-client#

We recommend using the pystac-client Python library. This library is specifically designed to interact with STAC Catalogs and APIs. Full documentation for this library can be found here: https://pystac-client.readthedocs.io/en/latest/.

Authentication#

There are two methods for sending authenticated requests to the STAC API: username/password- and token- based authentication.

Username / Password-based authentication#

A description of basic authentication can be found on the Basic access authentication Wikipedia page. The short version is that your request should include an “Authorization” header of the form:

Authorization: Basic <credentials>

The credentials should be your username and password separated by a “:” character and base-64 encoded. Almost any client you use to access the STAC API is going to abstract these details away, though, and just allow you to specify a username and password.

Token-based authentication#

Requests using Token-based authentication should include an “Authorization” header of the form:

Authorization: Bearer <token>

The benefit of this approach is that requests can be sent without the calling code having to know the username or password.

A token can be created using the STAC API’s “/token” webpage. In the staging environment, for example, you would browse to https://fusion-stac.hydrosat.com/token . That page will redirect you to a login page where you’ll enter your username and password. It will then redirect you back to a webpage that will display a token.

Just like password-based authentication, most client libraries will allow you to specify a token and will abstract away the header details.

Unauthenticated access#

Unauthenticated requests to the STAC API will generally return the same results as authenticated access. The only different at the moment is that item assets will not be returned if a user is not authenticated, while authenticated requests will see item assets with pre-signed S3 URLs that will allow the assets to be accessed.

Collections#

Items describing data products are organized within Collections where each Collection contains Items of a similar type. A list of current Collections can be retrieved from the Collections endpoint:

curl#

curl --location --request GET 'https://fusion-stac.hydrosat.com/collections' \
--header 'Content-Type: application/json'

pystac client#

# replace with your username and password
userpass = 'your-username:your-password'
b64 = base64.b64encode(userpass.encode()).decode()
headers = {'Authorization':'Basic ' + b64}

endpoint = 'https://fusion-stac.hydrosat.com'
catalog = Client.open(cat_url, headers=headers)
collections = catalog.get_children()
for collection in collections:
    print(f"{collection.id} - {collection.title}")

Collection Descriptions#

The Collection names below are for the baseline products and the inputs to those products. Collections ending with _evaluation contain experimental versions of the same products that may use new processing methods.

Collection Name	Description
prepped_inputs_s2	The prepared Sentinel-2 multispectral surface reflectance inputs at 20 m resolution.
prepped_inputs_landsat	The prepared Landsat 8 and Landsat 9 land surface temperature inputs resampled to 30 m resolution.
prepped_inputs_mcd43a4	The prepared MODIS surface reflectance inputs at 500 m resolution from the MCD43A4 dataset.
prepped_inputs_mod21a1d	The prepared MODIS land surface temperature inputs at 1 km resolution from the MOD21A1D dataset.
pydms_sharpened_modis	Downscaled MODIS land surface temperature at 500 m resolution.
pydms_sharpened_landsat	Downscaled Landsat land surface temperature at 20 m resolution.
starfm_predictions_modis_landsat	Daily land surface temperature (HDST) at 20 m resolution derived from fusion.

STAC Query Examples#

Querying the STAC server can be accomplished in a variety of ways. Collections available to search in the Hydrosat Fusion Hub STAC catalog include (primary collections in bold):

starfm_predictions_modis_landsat - Predicted LST using MODIS and Landsat-8 / Landsat-9
pydms_sharpened_landsat - Sharpened LST using Sentinel-2 and Landsat-8 / Landsat-9

Below are examples using the curl CLI tool and pystac-client, a Python library designed for STAC interaction. To return a complete timeseries of data, both of the collections listed above must be specified to the search query.

curl#

curl --location --request POST 'https://fusion-stac.hydrosat.com/search' \
-u 'MY_USERNAME:MY_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw ' {
    "collections": ["starfm_predictions_modis_landsat", "pydms_sharpened_landsat"],
    "bbox": [-119.87193746197875,36.573072227599425, -119.84859151471318,36.604084686243],
    "datetime": "2021-08-17T00:00:00Z/2021-08-18T00:00:00Z"
}'

pystac-client#

A basic example of pystac-client to query the Hydrosat Fusion Hub STAC holdings follows.

# define the API endpoint
endpoint = 'https://fusion-stac.hydrosat.com/'

# define a spatio-temporal search envelope using a dictionary
search_kwargs = {
    'collections': ['starfm_predictions_modis_landsat', 'pydms_sharpened_landsat'],
    'bbox': [-94.779052734375, 41.918628865183045, -95, 42],
    'datetime': ["2022-01-17T00:00:00Z", "2022-01-17T00:00:00Z"]
}

# define authorization headers as described above
your_token = 'some_token'
headers = {
    'Authorization': f'Bearer {your_token}'
}

# open the catalog, passing in headers 
cat = Client.open(endpoint, headers=headers)

    logging.info(f"Serching {endpoint}")
    search = cat.search(**search_kwargs)
    logging.info(f"{search.matched()} items found.")
    items = search.get_all_items()
    for item in items:
        print(item.id)

Please note that further search keyword arguments are available, as described in the documentation linked above. Also note that the ‘datetime’ value can be either a list of date-formatted strings, or a single string, with the two dates delimited with a forward slash ‘/’.

Orders Service#

For convenience, we provide a service that allows:

Spatial clipping of data to an area of interest
Reprojection of data into any EPSG-defined projection

To submit an order, an order configuration definition is described in JSON and passed to the orders endpoint. An order id and corresponding url is returned, which can be polled for the status of the order. When the order is complete, a description of the order and download links will be returned.

The following table describes the parameters of the orders service:

Parameter	Type	Required	Default/Example
start_date	date string	Yes	“2022-08-10”
end_date	date string	Yes	“2022-08-10”
projection	valid epsg code	Yes	“epsg:32611”
resolution	int, float, or pair of float	No	(20.0, 20.0)
output_format	string (allowed values)	No	“GeoTIFF” or “NITF”
collections	list of collection id strings	Yes	[“starfm_predictions_modis_landsat”, “starfm_predictions_viirs_landsat” ]
assets	list of string asset ids to prepare	No	All assets in specified collections
geometry	GeoJSON Polygon	Yes	“geometry”: { “coordinates”: [[ [-119.86283939192722,36.5978831890637], …,]] “type”: “Polygon”}
bbox	GeoJSON Bounding Box	No	derived from geometry if not provided

curl#

curl --location --request POST 'https://fusion-stac.hydrosat.com/orders' \
-u 'MY_USERNAME:MY_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw ' {
    "start_date": "2021-08-17",
    "end_date": "2021-08-18",
    "projection": "epsg:32610",
    "resolution": 20.0,
    "output_format": "GeoTIFF",
    "collections": [
      "starfm_predictions_modis_landsat",
        "pydms_sharpened_landsat"
    ],
    "assets": [
      "lst",
      "combined_qa"
    ],
    "geometry": {
        "coordinates": [
          [
            [-119.86283939192722,36.5978831890637],
            [-119.86283939192722,36.590440737292596],
            [-119.85391300032569,36.590440737292596],
            [-119.85391300032569,36.59788318906374],
            [-119.86283939192722,36.59788318906374]
          ]],
        "type": "Polygon"}
}'

curl --location --request GET 'https://fusion-stac.hydrosat.com/orders/MY_ORDER_ID' \
-u 'MY_USERNAME:MY_PASSWORD' \
--header 'Content-Type: application/json'

python#

import time
payload = {
    "start_date": "2021-08-17",
    "end_date": "2021-08-18",
    "projection": "epsg:32610",
    "resolution": 20.0,
    "output_format": "GeoTIFF",
    "collections": [
      "starfm_predictions_modis_landsat",
        "pydms_sharpened_landsat"
    ],
    "assets": [
      "lst",
      "combined_qa"
    ],
    "geometry": {
        "coordinates": [
          [
            [-119.86283939192722,36.5978831890637],
            [-119.86283939192722,36.590440737292596],
            [-119.85391300032569,36.590440737292596],
            [-119.85391300032569,36.59788318906374],
            [-119.86283939192722,36.59788318906374]
          ]],
        "type": "Polygon"}
}

order_url = 'https://fusion-stac.hydrosat.com/orders'
p = requests.post(order_url, headers=headers, json=payload)

t0 = time.time()
status = 'pending'
while requests.get(p.json()['url'], headers=headers).json()['status'] == 'pending':
    time.sleep(15)
    pass

t1 = time.time()
print(f'finished in {(t1-t0)/60:0.02f} minutes')
g = requests.get(p.json()['url'], headers=headers)
res = g.json()
g.json()

For more information on how to work with the API, see our How-To Guides.

API Reference and Specification

Contents

API Reference and Specification#

Spatiotemporal Asset Catalog API#

curl#

pystac-client#

Authentication#

Username / Password-based authentication#

Token-based authentication#

Unauthenticated access#

Collections#

curl#

pystac client#

Collection Descriptions#

STAC Query Examples#

curl#

pystac-client#

Orders Service#

curl#

python#