Tasking

Tasking with the API Platform

The ICEYE Tasking API provides an integration point for your tasking systems, enabling you to schedule tasks with the ICEYE satellite constellation up to 14 days in advance. The following diagram gives an overview of an interaction between a typical client UI and the ICEYE system, from the time of task creation until the time when the SAR data products are ready for download.

Tasking overview

During a normal tasking 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 the 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 (the timeout value, currently 3600 seconds, is returned in the authentication response).

  2. Create a task — after prompting the user to enter the parameters for an image tasking request, the client requests a task with a single createTask API invocation.

    At a minimum, the following parameters must be provided:

    • Point of interest

    • Acquisition window

      • Start time

      • End time

    • Imaging mode

    The following optional parameters can also be provided:

    • Incidence angle

    • Look side

    • Pass direction

    • Exclusivity

    • Task priority

    On receiving the request, the server checks the following:

    • Whether the request syntax is correct

    • Whether the task is contractually feasible

    • Whether the price of the task is within budget

    If the request fails any of these checks, the server immediately returns an error response.

  3. Check task status — 20 minutes after receiving the task, the scheduler finishes evaluating the task feasibility and updates the tasks status accordingly, changing it to ACTIVE or REJECTED. To check the outcome, the client invokes the getTask operation to obtain the current task status.

    You can call getTask at any point in the flow to check the task status.

  4. Wait for availability — as there is a gap between the time of task creation and the time when the image becomes available, the client needs to be aware of the timing of image availability. The time when the standard SAR data products become available for download can vary within the following range:

    • Earliest availability = start of acquisition time window + downlink time + processing time

    • Latest availability = end of acquisition time window + downlink time + processing time

    The time to availability is defined as downlink time + processing time and the standard SLA for this is 8 hours.

    To find out if the task’s standard products are available, the client can ping the Tasking API with the getTask operation to check the task status. The FULFILLED status indicates that the standard products are ready for download.

  5. Get task product URLs — when the standard SAR data products become available for download, the client can obtain the list of SAR products and their corresponding download URLs by invoking the listTaskProducts operation

    Non-standard SAR data products require additional processing and are typically available for download within one hour of the standard SAR data products. Depending on the server load, however, there can be significant variability in the processing time, and ICEYE provides no specific guarantees relating to the processing time for non-standard data products.

  6. Download task products — the client downloads the SAR data products using the URLs obtained in the previous step.

Fleet tasking

Fleet tasking is a form of tasking where all available satellites in the constellation are taken into consideration when a user submits a task request. That is, any satellite in the constellation might be tasked to acquire the image. This approach has the advantage that there is a much higher probability of acquiring an image in your acquisition window.

Note the following characteristic features of fleet tasking:

  • Does not require mission planning

  • Evaluates task feasibility across the entire constellation

  • Specifies location as a point of interest

ICEYE will be releasing more tasking options over time as part of its API product roadmap.

Location and time of acquisition

For a fleet task, the appropriate way to specify the location and time of acquisition is, as follows:

  • Point of interest — to specify the area of interest for a fleet task, you provide the coordinates of a single point, in the form of a latitude/longitude pair in the WGS 84 coordinate system. The specified point represents the center of the area of interest and the size of the image about this point is implicitly defined by the imaging mode.

    The orientation can be left unspecified, in which case it is subject to ICEYE optimization. Alternatively, you can specify the optional incidence angle, look side, and pass direction parameters.

  • Acquisition window — to specify the acquisition time for a fleet task, you specify an acquisition time window (at least 24h wide), which defines a window of time during which one of the satellites in the constellation could acquire the image.

Rejection policy

The rejection policy refers to the process whereby the ICEYE scheduler calculates the probability of acquiring the desired image at the specified location and within the specified acquisition time window (subject also to any other constraints specified by the user). If the acquisition probability is too low, the task is rejected.

The minimum required inputs are the point of interest, acquisition window, and imaging mode. You can further constrain the acquisition with specific look side, pass direction, and width of incidence angle. However, the more constraints you place on image collection, the lower the likelihood that the ICEYE scheduler will find a suitable opportunity to acquire the image.

For the purposes of mission planning, the position of the satellites in the ICEYE constellation are publicly available and can be found using online orbital elements tools such as celestrak or n2yo, which provide a live view of the current ICEYE constellation. However, it is not always necessary to perform mission planning before attempting to create a fleet task. An alternative strategy is to exploit the feasibility checking step that is built into the createTask operation. This enables you to adopt a trial-and-error approach to tasking. By invoking createTask, you can check the feasibility of tasking for a certain combination of parameters and then, if the task is rejected, try again with a different combination of parameters.

20 minute feasibility response time

When you submit a task request through the API (by invoking createTask), the ICEYE scheduler is guaranteed to calculate the task feasibility within 20 minutes of task submission. If the estimated probability of acquisition is sufficiently high (in the case of COMMERCIAL priority, above 90%), the task status is set to ACTIVE, otherwise it is set to REJECTED.

The estimated probability of acquisition never quite reaches 100%, for reasons that include: orbit shift, unplanned satellite maintenance, preemption by an emergency order (rare), and other factors outside the control of ICEYE.

Backoff strategy

In the case of task rejection (task status set to REJECTED), the recommended approach is to retry tasking with looser parameters. You can implement an effective backoff strategy by modifying the following tasking parameters, as you retry the createTask invocation:

  • Acquisition time window — widen the time window. The minimum width of the time window is 24 hours. Choosing a wider time window increases the likelihood of image collection.

  • Incidence angle — widen the acceptable angle range, where the widest range is between 10 and 45 degrees. But note that the incidence angle also affects image resolution (see ICEYE Product Specification) and there can be a loss of image quality at either extreme. See Incidence angle.

  • Look side — set to ANY (or leave unspecified).

  • Pass direction — set to ANY (or leave unspecified).

  • Task priority — if you previously tried with BACKGROUND priority, try setting the priority to COMMERCIAL.