List catalog items

GET /catalog/v1/items

By invoking the listCatalogItems operation you can browse the entire ICEYE public catalog. A variety of optional query parameters enable you to filter the search in a variety of ways, for example by specifying a bounded box or a date-time range. The search result is returned as a list of STAC items (GeoJSON features).

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).

Query 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 that includes the cursor query parameter, setting it equal to the cursor value from the previous response. On success, the next page of results is returned, potentially including a new cursor to continue walking the list.

You can customize the number of returned catalog items by providing a limit query parameter, which specifies the maximum number of items to return in the response.

By default, up to 10 catalog items are returned in each response.

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

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"

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 -v -G "${API_BASE_URL}/api/catalog/v1/items" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data-urlencode "ids=${ID1},${ID2},${ID3}"

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 -G "${API_BASE_URL}/api/catalog/v1/items" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data-urlencode "bbox=119.53279,11.403177,120.86618,12.626827"

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 -G "${API_BASE_URL}/api/catalog/v1/items" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data-urlencode "datetime=2019-09-07T09:37:37Z"

Sorting results

You can sort the results returned by the listCatalogItems operation by specifying the sortby query parameter. The syntax of the sortby parameter is a comma-separated list of properties, prefixed by a ` sign for ascending order, or a `-` sign for descending order (if the sign is omitted, it defaults to `) — for example:

sortby=+properties.name1,-properties.name2

In this property list, you can reference any of the properties returned in the body of a listCatalogItems response. The following table shows some of the more useful sorting properties (not an exhaustive list):

Property Description

properties.start_time

Start of the acquisition time window.

properties.end_time

End of the acquisition time window.

properties.image_mode

Imaging mode.

properties.incidence_angle

Incidence angle.

properties.observation_direction

Equivalent to look side (left or right).

properties.orbit_state

Equivalent to pass direction (ascending or descending).

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

curl -G "${API_BASE_URL}/api/catalog/v1/items" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data-urlencode "sortby=+properties.start_time,+properties.image_mode"

Example

Request

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

curl -v --location "${API_BASE_URL}/api/catalog/v1/items" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}"

Response

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

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