Search catalog items

POST /catalog/v1/search

The searchCatalogItems endpoint provides an alternative to the listCatalogItems operation for accessing the contents of the ICEYE public catalog, following the STAC API - Item Search specification. This endpoint supports the POST request method, as recommended in the specification, and enables an advanced query syntax based on the STAC API - Query Extension Specification.

Avoid caching item IDs for long periods. Catalog images are liable to be reprocessed from time to time, making the item IDs invalid.

For longer term storage, we recommend caching the corresponding frame ID (available from the properties.frame_id property of a STAC item).

Optional parameters

Paginated results

When a cursor property appears in the response, it indicates that more results are available. To access the next page of results, send a follow-up request with the cursor query parameter to the GET /catalog/v1/items endpoint (not the POST /catalog/v1/search endpoint).

The steps for accessing paginated results from a catalog search are, as follows:

  1. Search the catalog by invoking the POST /catalog/v1/search endpoint.

  2. If the number of search results exceeds the limit value, a cursor value is returned in the response.

  3. To get the remaining results, send a request to GET /catalog/v1/items with the given cursor value:

     curl -G "${API_BASE_URL}/api/catalog/v1/items" \
 --header "Accept: application/json, application/problem+json" \
 --header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
 --data-urlencode "cursor=XXXXXXXXXX" \
 --data-urlencode "limit=20"

  4. Repeat sending requests to GET /catalog/v1/items with successive cursor values until all the results have been retrieved.

By default, up to 10 catalog items are returned in each response and this limit can be customized by setting the limit query parameter.

It is not possible to retrieve paginated results directly from the /catalog/v1/search endpoint.

Filtering by STAC metadata query

You can perform advanced filtering of results from the searchCatalogItems operation using the query attribute in the JSON request body (as defined by the STAC API - Query Extension Specification).

The query attribute is defined as a JSON Object, with the following syntax:

{
  "query": {
    "PROPERTY_NAME": {
      "OPERATOR": VALUE
    }
  }
}

Where PROPERTY_NAME is the name of a STAC item property, which gets filtered by one or more OPERATOR/VALUE pairs, using the following operators:

Operator Description

eq

Filter for property values equal to the specified VALUE (case insensitive for strings).

neq

Filter for property values not equal to the specified VALUE (case insensitive for strings).

lt

Filter for property values less than the specified VALUE.

lte

Filter for property values less than or equal to the specified VALUE.

gt

Filter for property values greater than the specified VALUE.

gte

Filter for property values greater than or equal to the specified VALUE.

startsWith

Filter for property values that start with the specified string VALUE (case insensitive for strings).

endsWith

Filter for property values end with the specified string VALUE (case insensitive for strings).

contains

Filter for property values that contain the specified VALUE as a substring (case insensitive).

in

Filter for property values listed in VALUE, where VALUE is specified as an array (case insensitive).

You can filter on the following properties in a metadata query (where this list can be expanded over time):

Property name Description

start_time

The time when the satellite started to acquire the image (specified in RFC 3339 date-time format).

end_time

The time when the satellite finished acquiring the image (specified in RFC 3339 date-time format).

image_mode

The imaging mode used to acquire the image.

instrument_mode

The sensor acquisition mode used to acquire the image (for example, SC, SM, SLH, SLEA).

product_type

The product types available for the STAC item.

observation_direction

The observation direction at the time of image acqusition (left or right).

orbit_state

The pass direction at the time of image acquisition (ascending or descending).

incidence_angle

The incidence angle at the time of image acquisition.

satellite_look_angle

The look angle at the time of image acquisition.

Instrument mode

The instrument mode describes the physical configuration of the satellite sensor that was used to acquire the image. Because each imaging mode requires a particular sensor configuration, there is a direct correspondence between the instrument_mode property values and the image_mode property values, as shown in this table.

Instrument mode / instrument_mode Imaging mode / image_mode

SM, stripmap

stripmap

SC, TOPSAR

scan

SL, SLH, spotlight

spotlight

SLF, SpotlightFine

spotlight_fine

SLEA

spotlight_extended_area

SLED, DWELL

spotlight_extended_dwell

SLEDF, DWELLF

spotlight_extended_dwell_fine

Example

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/catalog/v1/search" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "query": {
    "start_time": {
      "gte": "2021-02-12T00:00:00Z",
      "lte": "2021-03-18T12:31:12Z"
    },
    "orbit_state": {
      "startsWith": "asc"
    },
    "product_type": {
      "in": [
        "SLC",
        "GRD"
      ]
    },
    "instrument_mode": {
      "in": [
        "SC",
        "TOPSAR"
      ]
    }
  }
}'

Filtering by ID

If you already have the IDs for some catalog items (for example, IDs from a previous query), you can request those specific items by setting the ids query parameter to a comma-separated list of IDs.

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/catalog/v1/search" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "ids": [
    "3aa6aafd94b78c26db9345e426147a7e9ce2ea121d5a28846ccb845c03098c6784268f100ad5eb8218c5421802b0f638ffce9e5b426a85e9affc1fb11cc55079639268784102e3242f9b66",
    "11c31b9b3532e61e8d4de6196480865775785a227e9e73eb3c978e0faf4e45871ed7a9d4ab5d05512978dffe8d488caeea3dbe465928c04bee5676ef34c9acaee39bf3c3a2ff30058a7af6"
  ]
}'

Filtering by bounding box

A bounding box is a standard way of specifying a geospatial coordinate range, as defined in GeoJSON RFC 7946. When you query the catalog, you can specify a bounding box to filter the results. Only those GeoJSON features that have a geometry intersecting the bounding box will then be returned in the response.

The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth):

  • South-west corner, longitude

  • South-west corner, latitude

  • Minimum value, elevation (optional)

  • North-east corner, longitude

  • North-east corner, latitude

  • Maximum value, elevation (optional)

The coordinate reference system of the values is WGS 84 longitude/latitude.

In most cases, the values in a bounding box are specified in the order: minimum longitude, minimum latitude, maximum longitude, maximum latitude. However, in cases where the box spans the antimeridian, the first value (west-most box edge) is larger than the third value (east-most box edge).

If the vertical axis (elevation) is included, the third and the sixth numbers are the bottom and the top of the 3-dimensional bounding box.

If a GeoJSON feature has multiple spatial geometry properties, it is the decision of the server whether only a single spatial geometry property is used to determine the extent or all relevant geometries.

For example, the bounding box of the New Zealand Exclusive Economic Zone in WGS 84 coordinates (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented in JSON as [160.6, -55.95, -170, -25.89] and in a query parameter as bbox=160.6,-55.95,-170,-25.89.

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/catalog/v1/search" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "bbox": [
    -5,
    28,
    56,
    44
  ]
}'

Filtering by date-time range

When you query the catalog, you can specify a date-time range to filter the results. Only those GeoJSON features with a temporal property that intersects the specified date-time range will be returned in the response.

Date and time (date-time) expressions follow RFC 3339.

A date-time range can be specified in any of the following formats (using / to indicate an interval and .. to indicate an open range):

Date-time range Description

2018-02-12T23:20:50Z

A specific date-time

2018-02-12T00:00:00Z/2018-03-18T12:31:12Z

A closed interval

2018-02-12T00:00:00Z/..

An open interval, with open end time

../2018-03-18T12:31:12Z

An open interval, with open start time

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/catalog/v1/search" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "datetime": "2021-02-12T00:00:00Z/2021-03-18T12:31:12Z"
}'

Sorting results

You can sort the results returned by the searchCatalogItems operation by specifying the sortby attribute in the JSON request body (as defined by the STAC API - Sort Extension Specification). The sortby attribute is specified as an array of sorting conditions, with the following syntax:

{
  "sortby": [
    {
      "field": "PROPERTY_NAME",
      "direction": "DIRECTION"
    }
  ]
}'

Where PROPERTY_NAME is the name of a STAC item property and DIRECTION can either be asc (for ascending order) or desc (for descending order).

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/catalog/v1/search" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "bbox": [
    -5,
    28,
    56,
    44
  ],
  "datetime": "2021-02-12T00:00:00Z/2021-03-18T12:31:12Z",
  "sortby": [
    {
      "field": "properties.product_type",
      "direction": "asc"
    },
    {
      "field": "id",
      "direction": "desc"
    }
  ]
}'

Example

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/catalog/v1/search" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "bbox": [
    -5,
    28,
    56,
    44
  ],
  "datetime": "2021-02-12T00:00:00Z/2021-03-18T12:31:12Z",
  "ids": [],
  "limit": 10,
  "query": {
    "start_time": {
      "gte": "2021-02-12T00:00:00Z",
      "lte": "2021-03-18T12:31:12Z"
    },
    "orbit_state": {
      "startsWith": "asc"
    },
    "product_type": {
      "in": [
        "SLC",
        "GRD"
      ]
    }
  },
  "sortby": [
    {
      "field": "properties.product_type",
      "direction": "asc"
    },
    {
      "field": "id",
      "direction": "desc"
    }
  ]
}'

Response

On success, returns a 200 status code and a JSON object containing an array of catalog items.

{
    "cursor": "XXXXXXXXXX",
    "data": [
        ...
    ]
}