Catalog

Browsing the Catalog

The Catalog API enables you to browse the contents of the ICEYE public catalog and to purchase specific items from the catalog.

Catalog overview

During a typical image purchasing flow, the client has the following series of interactions with the ICEYE system:

  1. Authenticate — from the user’s perspective, the first step of the interaction with the ICEYE system is to log in with username/password credentials. Under the hood, the client combines the user credentials with customer’s API key and authenticates the user by sending a request to the ICEYE token endpoint.

    The response from the token endpoint contains a bearer token, which authenticates the API calls throughout the user session (and is valid for a limited period of time).

  2. List catalog items — to browse the items in the catalog, the client invokes the listCatalogItems operation, providing a variety of filter parameters to search for the images. The listCatalogItems operation returns a list of STAC items (identical to GeoJSON features).

  3. Purchase catalog items — the client UI enables the user to select specific catalog items for purchase. The client code then extracts the IDs of the selected items and passes the list of IDs to the purchaseCatalogItems operation, accompanied by the contract ID (which determines the account used for purchasing). If the invocation is successful, the order is submitted to the ICEYE ordering processing system.

  4. Get purchase status — as it typically takes some time to process the catalog order, the client checks the status by invoking the getPurchasedItem operation. When the status transitions to closed, this indicates that the order has completed successfully and the image products are available for download.

  5. Download products — the catalog images are available to download from a standard delivery location, which is configured at the time the contract is set up (for example, SFTP or AWS S3 storage). The delivery location needs to be configured only once, and it can then be reused for all subsequent purchase requests through the API.

    For example, if you choose to accept delivery of data products through AWS S3, the COSP team would give you access to a specific directly on AWS S3. Subsequently, when you purchase data products through the Catalog API, the ordering system automatically creates a subdirectory to deliver the data products.

    In an upcoming release, the Catalog API will provide API operations that enable you to fetch the download links for your purchased products.