Overview¶

This document explains the structure of a STAPI Order request which is used for placing orders.

Ordering with loosely defined order values will give the provider more freedom to schedule. Define the values strictly to increase the chance of the preferred capture moment.

POST /products/{productId}/orders¶

Create Order Request¶

The endpoint POST /products/{productId}/orders is parameterized in the following way:

Path Parameters¶

Name	Type	Description
productId	string	Product identifier. The ID should be unique and is a reference to the queryables which can be used in the filter field.

Body Fields¶

Name	Type	Description
datetime	string	REQUIRED. Time interval with a solidus (forward slash, `/`) separator, using RFC 3339 datetime, empty string, or `..` values.
geometry	GeoJSON Geometry Object	REQUIRED. Defines the full footprint that the tasked data will be within.
filter	CQL2 JSON	A set of additional parameters in CQL2 JSON based on the queryables exposed in the product.
order_parameters	JSON Object	Order Parameters properties that can be used when creating an Order, reference Order Parameters

datetime¶

The datetime parameter represents a time interval with which the temporal property of the results must intersect. This parameter allows a subset of the allowed values for a ISO 8601 Time Interval or a OAF datetime parameter. This allows for either open or closed intervals, with end definitions separated by a solidus (forward slash, /) separator. Closed ends are represented by RFC 3339 datetimes. Open ends are represented by either an empty string or ... Only singly-open intervals are allowed. Examples of valid datetime intervals include 2024-04-18T10:56:00+01:00/2024-04-25T10:56:00+01:00, 2024-04-18T10:56:00Z/.., and /2024-04-25T10:56:00+01:00

geometry¶

Provides a GeoJSON Geometry Object, which must be an embedded GeoJSON object compliant to RFC 7946, section 3.1. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on WGS 84.

order_parameters¶

Order Parameters define the properties that can be used when creating an Order. These are different than Queryables, in that they do not constrain (filter) the desired results, but rather define general properties of an entire order For example, an order parameter might define what file format or what cloud service provider that the order will be delivered in.

By default, the absence of any defined order parameters on a product would indicate that only an empty object is valid.

Create Order Response¶

The response is using HTTP status code 201 and provides the location of the newly created order, which points to GET /order/{orderId}.

Example:

HTTP 201 Created
Location: https://example.com/orders/123

GET /orders¶

Get Orders Response¶

Field Name	Type	Description
orders	[Order Object]	REQUIRED. A list of orders.
links	Map\	REQUIRED. Links for e.g. pagination.

GET /orders/{id}¶

Get Order Response¶

See Order Object.

Order Object¶

Field Name	Type	Description
id	string	Unique provider generated order ID
user	string	User or organization ID ?
created	datetime	When the order was created
status	Order Status Object	Current Order Status object
links	[Link Object]
product_id	string	REQUIRED. Product identifier. This should be a reference to the Product being ordered.
request	Opportunity Request	Search parameters for Order
type	string	REQUIRED. Type of the GeoJSON Object. Must be set to `Feature`.
stapi_type	string	REQUIRED. Type of the STAPI Object. Must be set to `Order`.
stapi_version	string	REQUIRED. The STAPI version the Order implements.

If the GET /orders/{orderId}/statuses endpoint is implemented, there must be a link to the endpoint using the relation type monitor.

Order Status¶

Field Name	Type	Description
timestamp	datetime	REQUIRED. ISO 8601 timestamp for the order status
status_code	string	REQUIRED. Enumerated status code
reason_code	string	Enumerated reason code for why the status was set
reason_text	string	Textual description for why the status was set
links	[Link Object]	REQUIRED. list of references to documents, such as delivered asset, processing log, delivery manifest, etc.

Links is intended to be the same data structure as links collection in STAC. Links will be very provider specific.

Enumerated status codes¶

Code status codes¶

received (indicates order received by provider and it passed format validation.)
accepted (indicates order has been accepted)
rejected (indicates order will not be fulfilled)
completed (indicates provider was able to successfully collect imagery)
cancelled (indicates provider was unable to collect imagery)
failed (indicates when an order could not be completed/proccesed successfully)
expired (indicates the order request window has expired and no collection was made)

Providers must support these statuses.

State machine intent (currently no mandate to enforce)

Received -> accepted or rejected.
Accepted -> completed or cancelled.

Optional status codes¶

Providers may support these statuses.

scheduled (indicates order has been scheduled, no longer subject to customer cancellation)
held (order held for manual review)
processing (indicates some sort of processing has taken place, such as data was downlinked, processed or delivered)
reserved (action needed by customer prior to acceptance, such as payment)

Extension status codes¶

Providers may support additional statuses through extensions. For example:

tasked (indicates tasking commands have been issued to the satellite/constellation)
user_cancelled (indicates that the user cancelled the request)

Enumerated reason codes¶

Code indicating why a status was set. These are just examples at the moment. No consensus has been achieved as to what reasons should be core and handled in the same way by all providers, and which should be by extension.

invalid_geometry (invalid should be renamed, means that a valid geometry failed business rules)
competition (e.g., failed tasking auction)
cloud_cover (imagery rejected for cloud coverage)
partial_delivery (indicates a file was processed and placed in catalog, used with processing)