Create task

The center-point over which the image will be acquired. The point of interest should be specified as a valid set of earth-centered coordinates, pointOfInterest[lat] and pointOfInterest[lon] (latitude and longitude), in WGS 84 coordinates.

A time window with a start and end during which ICEYE’s constellation can acquire the SAR Data.

The timestamp format follows RFC 3339. To specify the same UTC time in a +3 hour timezone, users can use:

Imaging mode defines how a satellite collects the imaging data, which affects the azimuthal length, swath width, ground resolution, and image quality of the final image.

The imaging modes described in the ICEYE Product Specification are mapped to the string value of the imagingMode parameter as follows:

For example, to specify the imaging mode as a parameter in a request body:

A string that can be used to identify tasks uniquely or group multiple tasks together for easier tracking. The reference parameter accepts UTF-8 characters but it has a limitation of 256 string length.

Exclusivity indicates whether the task products should be released to the public catalog or remain within the customer’s private catalog for an agreed period of time (as reflected both in the pricing and the contractual agreement).

Task exclusivity can take one of the following string values:

For example, to specify exclusivity as a parameter in a request body:

The task priority specifies the priority level that applies when the scheduler has to resolve a potential conflict. In the case of a conflict, a COMMERCIAL task will always take priority over a BACKGROUND task.

Task priority can take one of the following string values:

Defaults to the contractually agreed priority from your contract.

For example, to specify the priority as a parameter in a request body:

The service level agreement (SLA) specifies a guaranteed availability time for tasked image products. The availability time is the time elapsed between the moment a satellite finishes acquiring the raw image, and the time when the image products become available for download from ICEYE.

The sla parameter can take one of the following string values:

Defaults to SLA_8H.

For example, to specify the SLA as a parameter in a request body:

The end user license agreement (EULA) defines the terms of use for purchased SAR products, also defining how widely products can be distributed. For full details of the EULA, see the relevant terms of your contract.

The eula parameter can take one of the following string values:

For example, to specify the EULA as a parameter in a request body:

The incidenceAngle parameter specifies the range of incidence angles that are accepted by this task.

The default incidence angle range is automatically set to the recommended range (Performant Incidence Range) of the specified imaging mode, as documented in the ICEYE Product Specification.

If you specify the incidenceAngle parameter explicitly, we recommend that you choose a range lying within the documented Performant Incidence Range for the specified imaging mode, in order to obtain a high quality image. Angle ranges wider than 10-45 degrees are disallowed, because incidence angles outside this range are not commercially supported in the constellation.

Possible values are ANY, LEFT and RIGHT. Default to ANY.

Possible values are ANY, ASCENDING and DESCENDING. Default to ANY.

You can specify the delivery location for products using the deliveries parameter. The deliveries parameter is an array of delivery objects, defined by the following properties:

For example, to specify delivery of products to AWS S3, in the folder1/folder2/ subpath of the DOC-EXAMPLE-BUCKET1 bucket:

You can optionally use a webhook to receive a notification whenever the task status changes — for example, to be notified when a tasked image becomes available for download from the delivery location (task status transitions to FULFILLED or DONE).

To use a webhook (which must already be registered with the Notifications API), provide the id of the registered webhook in the notifications parameter, as follows:

The notifications flow works as follows:

For more details, see Notifications.

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

On success, customers will receive a 201 status code and a JSON object containing the recently created Task with a RECEIVED status.

Indicates that the request was malformed.

Example error when the contract budget is insufficient to cover the cost of tasking:

Verify that you are tasking a valid combination of parameters that are compatible with the contract. A quick way to verify is to confirm that you can request a price for the same combination of parameters using the getTaskPrice operation. If you cannot, debug the error using these common error messages.

If you can successfully call the getTaskPrice operation, verify that you have enough funds in your contract to cover the cost of the task. Call the getSummary operation to check your current balance. Calculate your remaining funds as outlined in the section available funds.

For more details, see Error handling.

Example error when the when the request was badly formed:

Please verify the contract is still active by checking its start and end using the GetContract operation. If your contract has expired, reach out to your sales representative to enter into a new contract negotiation.