Catalog Advanced Querying

The SatVu platform provides a comprehensive interface to query the historical data catalog via the API and SDK. Querying capabilities are supported by the core STAC specification and the STAC filter extension which is an interface to the Common Query Language 2 (CQL2). The filter extension enables the querying of data by combining different operators and the majority of metadata fields.

Core STAC search

STAC specification standardises the way geospatial asset metadata is structured and queried. The core set of fields that are supported to be queried are:

Image IDs - defined in the ids parameter. Once defined, all other parameters are ignored.
Geometry - defined as an intersecting GeoJSON geometry object via the intersects parameter or a bounding box via the bbox parameter.
Date and time range - defined in the datetime parameter. Could be open or closed range.
Collections - defined in the collections parameter.

Advanced CQL2 filtering

CQL2 supports different types of filters that, in combination, allow a comprehensive query to be built. Each of the filters is defined by an operator op and a set of arguments args. The following represents four of the main types of filters:

andOrExpression: Used for combining multiple filters with logical and or or operations.
notExpression: Used to negate a filter or group of filters. The operator value is not
comparisonPredicate: Used to compare values, such as greater than, less than, equal, etc. This filter itself is also categorised into:
- The binaryComparisonPredicate that is used to compare two values and supports common comparison operators.
- The isNullPredicate checks if a property’s value is null. The operator value is isNull.
boolean: Used for simple true/false conditions.

Common comparison operators

= is “Equal”.
!= or <> is “Not equal”.
> is “Greater than”.
< is “Less than”.
>= is “Greater than or equal to”.
<= is “Less than or equal to”.

Conformance classes

SatVu catalog search API provides an endpoint that lists supported conformance classes. The endpoint GET /conformance returns the list of links to relevant conformance class documentation.

Here is a subset of the response:

{
    "conformsTo": [
        "https://api.stacspec.org/v1.0.0/core",
        "https://api.stacspec.org/v1.0.0/collections",
        ...
    ]
}

Queryables

SatVu catalog search API supports the majority of scene metadata fields for filtering. The full list is available in the GET /queryables endpoint. You can also find the summary in Catalog search and order.

Here is a subset of the response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.satellitevu.com/queryables",
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "format": "date"
    },
    "eo:cloud_cover": {
      "type": "number"
    }
    {
      ...
    }
  }
}

Examples

Please note, every one of the following examples suggests that you have set up the CONTRACT_ID and the ACCESS_TOKEN values:

export CONTRACT_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
export ACCESS_TOKEN="xxx…xxx"

The examples will also focus on searching only the acquisition collection of the catalog, since this is the parent collection of downstream collections.

See Catalog Structure for more information on how the STAC catalog is structured.

Geographical query

Here is a basic catalog query that returns images in a defined geometry.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "collections": ["acquisition"],
  "intersects": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -6.327503392573107,
          61.6683280553836
        ],
        [
          -10.397971713272113,
          35.326504973149014
        ],
        [
          33.47533491237101,
          43.802022041567994
        ],
        [
          -6.327503392573107,
          61.6683280553836
        ]
      ]
    ]
  }
}'

Geographical and date and time range query

In addition to search by geometry, the core STAC search supports querying by the date and time information. Here is an example of integrating querying by the image acquisition time in addition to the geometry.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "datetime": "2023-06-01T00:00:00.000Z/2023-08-31T00:00:00.000Z",
  "collections": ["acquisition"],
  "intersects": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -6.327503392573107,
          61.6683280553836
        ],
        [
          -10.397971713272113,
          35.326504973149014
        ],
        [
          33.47533491237101,
          43.802022041567994
        ],
        [
          -6.327503392573107,
          61.6683280553836
        ]
      ]
    ]
  }
}'

Advanced image metadata querying

Single metadata field and operator

The following query returns images where the cloud coverage is less than 15 percent.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "collections": ["acquisition"],
  "filter": {
    "op": "<",
    "args": [
      { "property": "eo:cloud_cover" },
      15
    ]
  }
}'

Single metadata field and combined operators

The following query combines two filters for the same metadata field - off-nadir angle. It returns images with the off-nadir angle greater than or equal to 15 degrees and less than 35 degrees.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "collections": ["acquisition"],
  "filter": {
    "op": "and",
    "args": [
      {
        "op": ">=",
        "args": [
          { "property": "view:off_nadir" },
          15
        ]
      },
      {
        "op": "<",
        "args": [
          { "property": "view:off_nadir" },
          35
        ]
      }
    ]
  }
}'

Combination of metadata fields

The following query combines filters for two different metadata fields: off-nadir angle and cloud coverage. You can see that a combination of queries for different metadata fields is done at the arguments level.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "collections": ["acquisition"],
  "filter": {
    "op": "and",
    "args": [
      {
        "op": "and",
        "args": [
          {
            "op": ">=",
            "args": [
              { "property": "view:off_nadir" },
              15
            ]
          },
          {
            "op": "<",
            "args": [
              { "property": "view:off_nadir" },
              35
            ]
          }
        ]
      },
      {
        "op": "<",
        "args": [
          { "property": "eo:cloud_cover" },
          15
        ]
      }
    ]
  }
}'

Limiting and sorting

The Catalog search query supports sorting and limiting the number of returned items. The following query returns the first 100 images in SatVu catalog.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "collections": ["acquisition"],
  "limit": 100,
  "sort": [
    {
      "field": "datetime",
      "direction": "asc"
    }
  ]
}'

Combination of STAC core and CQL2 filter querying

Both core STAC and CQL2 filter queries can be combined into a single query. The following example shows a request to return all catalog items within a defined timeframe, specific geometry, a specific range of off-nadir angles and a maximum cloud coverage value. The response is limited to 100 items and is sorted from older to newer images.

curl -X POST "https://api.satellitevu.com/catalog/v1/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "datetime": "2023-06-01T00:00:00.000Z/2023-08-31T00:00:00.000Z",
  "collections": ["acquisition"],
  "intersects": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -6.327503392573107,
          61.6683280553836
        ],
        [
          -10.397971713272113,
          35.326504973149014
        ],
        [
          33.47533491237101,
          43.802022041567994
        ],
        [
          -6.327503392573107,
          61.6683280553836
        ]
      ]
    ]
  },
  "filter": {
    "op": "and",
    "args": [
      {
        "op": "and",
        "args": [
          {
            "op": ">=",
            "args": [
              { "property": "view:off_nadir" },
              15
            ]
          },
          {
            "op": "<",
            "args": [
              { "property": "view:off_nadir" },
              35
            ]
          }
        ]
      },
      {
        "op": "<",
        "args": [
          { "property": "eo:cloud_cover" },
          15
        ]
      }
    ]
  },
  "limit": 100,
  "sort": [
    {
      "field": "datetime",
      "direction": "asc"
    }
  ]
}'

Core STAC search​

Advanced CQL2 filtering​

Common comparison operators​

Conformance classes​

Queryables​

Examples​

Geographical query​

Geographical and date and time range query​

Advanced image metadata querying​

Single metadata field and operator​

Single metadata field and combined operators​

Combination of metadata fields​

Limiting and sorting​

Combination of STAC core and CQL2 filter querying​