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 the uuids in the "id" field.

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

Pagination

Queries made to the collections, items or search endpoint all support pagination. To paginate include the query parameters offset and limit in your query:

curl -X GET "https://api.hubocean.earth/api/stac/collections?offset=10&limit=10"

If you include pagination parameters in your request we will add next and prev links to your response that you can use to traverse the data in your own pace.

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 collection ids to search in. Example: "[d0d0b53a-f598-46a3-a4c3-7c539f626956]"
ids	Comma-separated list of item UUIDs to filter by. Example: ["eac0399f-82e3-4536-915f-7e1dca90d032","99a3e108-9115-4841-bdb5-131d6cb52c3c"]
bbox	Bounding box for spatial filtering [minX, minY, maxX, maxY]. Example: [-180,-90,180,90]
intersects	GeoJSON geometry to search within. Example: { "type": "Polygon", "coordinates": [[[4.95, 54.95], [5.05, 54.95], [4.95, 55.05], [4.95, 54.95]]] }
datetime	Time range filter in ISO 8601 format. Example: "2020-01-01T00:00:00Z/2024-01-02T00:00:00Z"
limit	Maximum number of results to return. Example: 10

Tip

For both collections and ids, refer to the "id" field in a /collections or /search response.

Example Request:

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

Request Body:

{
  "collections": ["d0d0b53a-f598-46a3-a4c3-7c539f626956"],
  "ids": ["eac0399f-82e3-4536-915f-7e1dca90d032","99a3e108-9115-4841-bdb5-131d6cb52c3c"],
  "bbox": "-180,-90,180,90",
  "intersects": {"type": "Polygon", "coordinates": [[[4.95, 54.95], [5.05, 54.95], [4.95, 55.05], [4.95, 54.95]]]},
  "datetime": "2020-01-01T00:00:00Z/2024-01-02T00:00:00Z",
  "limit": 10
}

Example using cURL:

curl -X POST "https://api.hubocean.earth/api/stac/search" \
     -d '{
           "collections": ["d0d0b53a-f598-46a3-a4c3-7c539f626956"],
           "ids": ["eac0399f-82e3-4536-915f-7e1dca90d032","99a3e108-9115-4841-bdb5-131d6cb52c3c"],
           "bbox": [-180,-90,180,90],
           "intersects": {"type": "Polygon", "coordinates": [[[4.95, 54.95], [5.05, 54.95], [4.95, 55.05], [4.95, 54.95]]]},
           "datetime": "2020-01-01T00:00:00Z/2024-01-02T00:00:00Z",
           "limit": 10
         }'

Example Response:

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

More Information

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