Hub Ocean STAC API Documentation

Introduction

The Hub Ocean STAC API provides access to our public catalog of geospatial datasets following the SpatioTemporal Asset Catalog (STAC) standard. This API enables users to explore, search, and retrieve geospatial data using standardized endpoints.

Base URL

https://api.hubocean.earth/api/stac

Capabilities

The API is STAC-compliant and supports the following capabilities:

• Catalog Root: Provides the main STAC catalog with links to collections and search functionality.
• Collections: Lists available datasets (collections) with metadata.
• Item Search: Supports search queries using spatial, temporal, and other filters.

STAC API Endpoints

Endpoint	Description	Method
/stac	Root Catalog	GET
/stac/collections	List available collections	GET
/stac/search	Search STAC items (GeoJSON)	POST

Example: Accessing Collections

To retrieve the list of available collections, send a GET request to:

GET https://api.hubocean.earth/api/stac/collections

Example using cURL:

curl -X GET "https://api.hubocean.earth/api/stac/collections"

Example Response:

{
  "collections": [
    {
      "id": "example-collection",
      "description": "Example dataset",
      "extent": { "spatial": ..., "temporal": ... },
      "links": [
        { "rel": "self", "href": "https://api.hubocean.earth/api/stac/collections/example-collection" }
      ]
    }
  ],
  "links": [
    { ... }
  ],
}

When getting a collection by id, we support look ups using both uuid and title.

curl -X GET "https://api.hubocean.earth/api/stac/collections/id"

Example: Searching for Items

To search for specific geospatial items, use the POST /stac/search endpoint with a JSON body specifying filters.

Search Parameters

Parameter	Description
collections	Comma-separated list of collections to search in. Example: "collection1,collection2"
ids	Comma-separated list of item IDs to filter by. Example: "item1,item2"
bbox	Bounding box for spatial filtering [minX, minY, maxX, maxY]. Example: "-180,-90,180,90"
intersects	GeoJSON geometry to search within. Example: { "type": "Point", "coordinates": [1, 2] }
datetime	Time range filter in ISO 8601 format. Example: "2020-01-01T00:00:00Z/2020-01-02T00:00:00Z"
limit	Maximum number of results to return. Example: 10

Example Request:

POST https://api.hubocean.earth/api/stac/search
Content-Type: application/geo+json

Request Body:

{
  "collections": "collection1,collection2",
  "ids": "item1,item2",
  "bbox": "-180,-90,180,90",
  "intersects": {"type": "Point", "coordinates": [1, 2]},
  "datetime": "2020-01-01T00:00:00Z/2020-01-02T00:00:00Z",
  "limit": 10
}

Example using cURL:

curl -X POST "https://api.hubocean.earth/api/stac/search" \
     -d '{
           "collections": "collection1,collection2",
           "ids": "item1,item2",
           "bbox": "-180,-90,180,90",
           "intersects": {"type": "Point", "coordinates": [1, 2]},
           "datetime": "2020-01-01T00:00:00Z/2020-01-02T00:00:00Z",
           "limit": 10
         }'

Example Response:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "item-123",
      "geometry": { "type": "Point", "coordinates": [5, 55] },
      "properties": { "datetime": "2023-06-15T12:00:00Z" },
      "links": [
        { "rel": "self", "href": "https://api.hubocean.earth/api/stac/items/item-123" }
      ]
    }
  ]
}

More Information

For further details, refer to the STAC Specification and the Hub Ocean Data Catalog.