STAC API - Sort Extension Specification

• STAC API - Sort Extension Specification
  • Overview
  • HTTP GET
  • HTTP POST JSON Entity

Overview

• Title: Sort
• OpenAPI specification: openapi.yaml
• Conformance Classes:
  • STAC API - Item Search binding: https://api.stacspec.org/v1.0.0/item-search#sort
  • STAC API - Features binding: https://api.stacspec.org/v1.0.0/ogcapi-features#sort
• Scope: STAC API - Features, STAC API - Item Search
• Extension Maturity Classification: Stable
• Dependencies:
  • STAC API - Item Search
  • STAC API - Features
• Owner: @philvarner

This specification defines a new parameter, sortby, that allows the user to define the fields by which to sort results. Only string, numeric, and datetime attributes of Item (id and collection only) or Item Properties (any attributes) may be used to sort results.

It is not required that implementations support sorting over all attributes, but implementations should return a 400 Bad Request status code when attempting to sort over a field name that does not support sorting. This specification does not yet require the implementation of an "-ables" endpoint (like CQL2 does for queryables) that defines the names of the fields that can be sorted over, so implementations must provide this out-of-band. Implementers may choose to require fields in Item Properties to be prefixed with properties. or not, or support use of both the prefixed and non-prefixed name, e.g., properties.datetime or datetime.

Sort behavior may be bound to either or both of STAC API - Item Search (/search endpoint) or STAC API - Features (/collections/{collectionId}/items endpoint) by advertising the relevant conformance class.

Fields may be sorted in ascending or descending order. The syntax between GET requests and POST requests with a JSON body vary. The sortby value is an array, so multiple sort fields can be defined which will be used to sort the data in the order provided (e.g., first by datetime, then by eo:cloud_cover).

NOTE: This specification may change, as our goal is to align with OGC API functionality, and sorting is currently being worked on as part of OGC API - Records, see this issue for the latest discussion.

HTTP GET

When calling a relevant endpoint using GET, a single parameter sortby with a comma-separated list of item field names must be provided. The field names may be prefixed with either "+" for ascending, or "-" for descending. If no sign is provided before the field name, it will be assumed to be "+". Note that + is used commonly by URL encoding as a space, so some tools may require escaping this literal + with a URL encoding of %2B.

Examples of sortby parameter:

1. GET /search?sortby=properties.created
2. GET /search?sortby=+properties.created
3. GET /search?sortby=properties.created,-id
4. GET /search?sortby=+properties.created,-id
5. GET /search?sortby=-properties.eo:cloud_cover

Note that examples 1 and 2 are symantically equivalent, as well as examples 3 and 4.

HTTP POST JSON Entity

When calling the relevant endpoint using POST withContent-Type: application/json, this adds an attribute sortby with an object value to the core JSON search request body.

The syntax for the sortby attribute is:

{
    "sortby": [
        {
            "field": "<property_name>",
            "direction": "<direction>"
        }
    ]
}

{
    "sortby": [
        {
            "field": "properties.created",
            "direction": "asc"
        },
        {
            "field": "properties.eo:cloud_cover",
            "direction": "desc"
        },
        {
            "field": "id",
            "direction": "desc"
        },
        {
            "field": "collection",
            "direction": "desc"
        }
    ]
}