/stat-api-spec

SpatioTemporal Asset Tasking API Spec

About

The SpatioTemporal Asset Tasking (STAT) API defines a JSON-based web API to query for potential future data and place orders ("tasking") for potential future data from remote sensing data providers (satellite or airborne).

STAT takes much of the work done by the STAC community and applies the lessons learned to this specification. The major departure from STAC is the requirement for uncertainty in many of the STAT properties.For example, a user requesting a data capture can provide a range of dates when they would like to capture. Conversely, a data provider cannot be certain of cloud cover in the future and must return a range of cloud cover probabilities to a user.

The STAT specifications define several new entities: Products, Opportunities, and Orders. These are
derived from the SpatioTemporal Asset Catalog (STAC) specification. Ideally, STAT requests to providers will be ultimately fulfilled via delivery of a STAC Item, so STAT aims to align with STAC core and extensions.

The core STAT specification provides a structure and language to describe Products, Opportunities, and Orders. The process of interacting with a data provider is done through a REST API.

STAT API Description

Core

The core of STAT API includes the /products endpoint and the /orders endpoint.

To know which constraints are available for which product_id, users first explore /products. These constraints can be used to form a POST to the /orders endpoint.

Landing Page

Fields that can be included in the response body for GET /.

Field Name Type Description
id string REQUIRED. Identifier for the API.
conformsTo [string] REQUIRED. Conformance classes that apply to the API globally.
title string A short descriptive one-line title for the API.
description string REQUIRED. Detailed multi-line description to fully explain the API. CommonMark 0.29 syntax MAY be used for rich text representation.
links [Link Object] REQUIRED. A list of references to other documents and endpoints.
Relation Types
Endpoint Relation Type
GET /conformance conformance
GET /products products
GET /products/{productId} product
GET /products/{productId}/parameters product-parameters
GET /orders orders
POST /orders create-order
GET /orders/{orderId} order
GET /orders/{orderId}/status status
POST /opportunities opportunities

create-order: A link with this relation type should only be provided in the landing page if a user can directly go from the products to the order endpoint without going through the POST /opportunities endpoint.

Opportunities

The /opportunities endpoint provides additional functionality on top of core and is designed to be used after /products and before /orders. It allows users more fine-grained control and selection of available tasking opportunities by letting them explore the opportunities which are available for a chosen order configuration. The opportunities are represented in a FeatureCollection, with order specific attributes and values in the feature properties.

Endpoints

STAT APIs follow the modern web API practices of using HTTP Request Methods ("verbs") and the Content-Type header to drive behavior on resources ("nouns") in the endpoints listed below.

The following table describes the service resources available in a STAT API implementation that supports all three of the foundation specifications. Note that the 'Endpoint' column is more of an example in some cases.

Endpoint Specified in Accepts Returns Description
GET / Core - Landing Page
GET /conformance Core - Conformance Classes
GET /products Core - Products Collection Figure out which constraints are available for which product_id
GET /products/{productId} Core - Product
GET /products/{productId}/parameters Core - JSON Schema
GET /orders Core - Orders Collection
GET /orderds/{orderId} Core - Order Object
POST /orders Core Order Request or any object - Order a capture with a particular set of constraints as defined in the products or a request that was provided through the opportunities endpoint.
POST /opportunities Opportunities Opportunity Request Opportunities Collection Explore the opportunities available for a particular set of constraints

Conformance Classes

STAT API utilizes OGC API Features Conformance JSON structure. For STAT API, we declare new STAT conformance classes, with the core ones detailed in the table below.

The core STAT conformance classes communicate the conformance JSON only in the root (/) document, while OGC API requires they also live at the /conformance endpoint. STAT's conformance structure is detailed in the core. Note all conformance URIs serve up a rendered HTML version of the corresponding OpenAPI document at the given location.

Conformance Class Table

Name Specified in Conformance URI Description
STAT API - Core Core https://stat-api.example.com/v0.1.0/core Specifies the STAT Landing page /, communicating conformance and available endpoints.
STAT API - Opportunities Opportunities https://stat-api.example.com/v0.1.0/opportunities Enables request of potential tasking opportunities
STAT API - Core Core https://geojson.org/schema/Point.json Allows submitting orders with GeoJSON points
STAT API - Core Core https://geojson.org/schema/Linestring.json Allows submitting orders with GeoJSON linestrings
STAT API - Core Core https://geojson.org/schema/Polygon.json Allows submitting orders with GeoJSON polygons
STAT API - Core Core https://geojson.org/schema/MultiPoint.json Allows submitting orders with GeoJSON multi points
STAT API - Core Core https://geojson.org/schema/MultiPolygon.json Allows submitting orders with GeoJSON multi polygons
STAT API - Core Core https://geojson.org/schema/MultiLineString.json Allows submitting orders with GeoJSON multi linestring

See the STAT API Demo