Home /UP42 API/Assets

CQL2 filters for STAC item search

Use CQL2 filters to search for specific STAC items.

Introduction

Common Query Language (CQL2) is a filter grammar that can be used for STAC item search.

A CQL2 filter consists of rules. Rules consist of arguments and operators. An argument is a value of a specific property you can choose from available filter parameters.

API parameters

ParameterOverview
filterobject
A CQL2 filter.
filter.argsarray of objects
Arguments inside of a CQL2 filter.
filter.opstring
Operators inside of a CQL2 filter.

Create a CQL2 filter for the /v2/assets/stac/search endpoint as follows:

  1. Find queryable filter parameters by calling the /v2/assets/stac/queryables endpoint.
  2. In filter.args, use a queryable filter parameter in the nested property field and follow it with a value.
  3. In filter.op, add an operator.

An example of a filter that searches for STAC items with cloud coverage less than 20%:

JSON 

    {
  "filter": {
    "op": "<",
    "args": [
      {
        "property": "eo:cloud_cover"
      },
      20.0
    ]
  }
}

Operators

Arithmetic operators

  • +: addition
  • -: subtraction
  • *: multiplication
  • /: division

Array operators

  • a_contains: search for STAC items that contain all array values in their parameters.
  • a_overlaps: search for STAC items that contain at least one array value in their parameters.
An example with a_contains

Returns STAC items with both optical and aerial in their tags.

JSON 

    {
  "filter": {
    "op": "a_contains",
    "args": [
      {
        "property": "tags"
      },
      ["optical", "aerial"]
    ]
  }
}

An example with a_overlaps

Returns STAC items with either optical or aerial in their tags.

JSON 

    {
  "filter": {
    "op": "a_overlaps",
    "args": [
      {
        "property": "tags"
      },
      ["optical", "aerial"]
    ]
  }
}

Comparison operators

  • =: equal to
  • !=: not equal to
  • <: less than
  • >: greater than
  • <=: less than or equal to
  • >=: greater than or equal to
  • isNull: the value is null
An example with >

Returns STAC items with cloud coverage of more than 20%.

JSON 

    {
  "filter": {
    "op": ">",
    "args": [
      {
        "property": "eo:cloud_cover"
      },
      20.0
    ]
  }
}

An example with isNull

Returns STAC items with no tags.

JSON 

    {
  "filter": {
    "op": "isNull",
    "args": {
      "property": "tags"
    }
  }
}

Logical operators

  • and: search for STAC items whose parameter values satisfy both arguments.
  • or: search for STAC items whose parameter values satisfy any of the arguments.
  • not: exclude STAC items whose parameter values satisfy the argument.
An example with and

Returns STAC items that have a ground sample distance less than or equal to 70 cm, and cloud coverage less than or equal to 20%.

JSON 

    {
  "filter": {
    "op": "and",
    "args": [
      {
        "op": "<=",
        "args": [
          {
            "property": "gsd"
          },
          0.7
        ]
      },
      {
        "op": "<=",
        "args": [
          {
            "property": "eo:cloud_cover"
          },
          20.0
        ]
      }
    ]
  }
}

An example with or

Returns STAC items that either have "constellation": "PNEO" or "collection_name": "pneo-tasking" in their parameters.

JSON 

    {
  "filter": {
    "op": "or",
    "args": [
      {
        "op": "=",
        "args": [
          {
            "property": "constellation"
          },
          "PNEO"
        ]
      },
      {
        "op": "=",
        "args": [
          {
            "property": "collection_name"
          },
          "pneo-tasking"
        ]
      }
    ]
  }
}

An example with not

Returns STAC items that don’t have "constellation": "PNEO" in their parameters.

JSON 

    {
  "filter": {
    "op": "not",
    "args": [
      {
        "op": "=",
        "args": [
          {
            "property": "constellation"
          },
          "PNEO"
        ]
      }
    ]
  }
}

Spatial operators

  • s_contains
  • s_crosses
  • s_disjoint
  • s_equals
  • s_intersects
  • s_overlaps
  • s_touches
  • s_within

How s_overlaps and s_intersects work

How s_contains, s_within, and s_intersects work


How s_equals and s_intersects work

How s_crosses and s_intersects work


How s_disjoint works

How s_touches works


An example with s_within

Returns STAC items whose AOIs are within the defined polygon.

JSON 

    {
  "filter": {
    "op": "s_within",
    "args": [
      {
        "property": "geometry"
      },
      {
        "type": "Polygon",
        "coordinates": [
          [
            [-123.47593244349214, 48.65881246874093],
            [-123.44562410769204, 48.65893370548264],
            [-123.44429739341179, 48.658161559812235],
            [-123.44376648785145, 48.65522725021609],
            [-123.47599504628167, 48.655076990420135],
            [-123.47602614621897, 48.65838026437638],
            [-123.47601340902926, 48.658758157043785],
            [-123.47593244349214, 48.65881246874093],
            [-123.47593244349214, 48.65881246874093]
          ]
        ]
      }
    ]
  }
}

An example with s_touches

Returns STAC items whose AOIs touch the defined line.

JSON 

    {
  "filter": {
    "op": "s_touches",
    "args": [
      {
        "property": "geometry"
      },
      {
        "type": "Point",
        "coordinates": [-123.47593244349214, 48.65881246874093]
      }
    ]
  }
}

Temporal operators

Use date and time in the ISO 8601 format: YYYY‐MM‐DDThh:mm:ssZ

  • t_after
  • t_before
  • t_contains
  • t_during
  • t_equals
  • t_finishes
  • t_finishedby
  • t_meets
  • t_metby
  • t_overlaps
  • t_overlappedby
  • t_starts
  • t_startedby

Temporal operators

An example with t_before

Returns STAC items acquired before March 21, 2023.

JSON 

    {
  "filter": {
    "op": "t_before",
    "args": [
      {
        "property": "datetime"
      },
      "2023-03-21T00:00:00.000Z"
    ]
  }
}

An example with t_overlaps

Returns STAC items acquired between March 21, 2023, and April 18, 2023.

JSON 

    {
  "filter": {
    "op": "t_overlaps",
    "args": [
      {
        "property": "datetime"
      },
      {
        "interval": ["2021-03-21T00:00:00.000Z", "2023-04-18T00:00:00.000Z"]
      }
    ]
  }
}

Learn more