Imagery Tasking
The Tasking API provides the tools for submitting and checking the status on imagery product collection — a tasking order. This service enables:
- the creation of tasking orders
- the retrieval of the order status and the collection progress
- the cancellation of existing orders
Once users have been authenticated, they can proceed to submit a task using the provided token.
What is a task?
A task is a request from a user to capture a single target one or many times in a given period. In other words, it is a request to generate a set of captures over the target that during the period where the Task is active, will cover the target a specific amount of times.
Task main attributes
Here we list the basic and mandatory attributes for a Task. From this basis, you can include additional attributes to tune your Task in different ways.
| Parameter | Type | Description |
|---|---|---|
| target | GeoJSON | Each Task is related to a single target. The target is a geographical polygon represented as GeoJSON. For POI product, the target must be a point. For AOI product, the target must be a polygon. |
| start | ISO Datetime | Tasks must specify a start and end. Those two attributes define the period where the Task will be active. After the period ends, the system will not generate any additional capture for the Task, regardless if the user obtained all the expected captures or not. |
| end | ISO Datetime | End of the task's period (see the start paremeter description) |
| product_id | integer | There are two types of products available for tasks: POI: to capture stripes & AOI: to capture an entire area in multiple stripes. To use each product, make sure your user has permission. |
| task_name | string | An identifier for the task |
| project_name | string | An identifier for the project related to the task (created under the hood). |
Task Lifecycle
A task is always linked to a status indicating the stage in the lifecycle where the task is.
When a task is created, the first status is always received. This means the task was created, and it will be considered in the planning process.
We still can not say if the captures for the task will be planned or not.
After the planning process finishes, there are two possible scenarios:
-
If the planning process generated planned captures for the task, then it will be moved to
pending -
If the planning process didn't generate planned captures for the task, then it will be moved to
planning
Once the capture has planned captures and is in pending status, it will be moved to in_progress 12 hours before the first capture takes place.
A task in in_progress status will be moved to completed once all the requested captures are completed (see the max_captures parameter definition). In case the task's end date is reached and not all the requested captures are completed the project will be moved to failed.
Additionally if the user cancels the task. The status will change to canceled.
Task states
| State | Description |
|---|---|
| received | The task was created, and it will be considered in the planning process. We still can not say if the captures for the task will be planned or not. |
| pending | The planning process considering the task was finished and generated planned captures on behalf of the task. |
| rejected | The feasibility analysis indicates we can not fulfill your order due technical reasons. Most likely we can not accomplish ONA and/or sun angle restrictions. |
| planning | The planning process finished, but it didn't generate any planned captures on behalf of the task. |
| in_progress | The task has planned captures for the future. The first planned capture has yet to happen and will happen in 12 hours or less. It is also possible the first capture already happened, and it will be more planned captures in the future. |
| canceled | A user manually canceled the task. The planned captures will be canceled (if possible). The task may have past captures already delivered. |
| failed | The task's period ended but none of the requested captures were taken. The order was not fulfilled. |
| completed | All the requested captures were captured. The order was fulfilled. |
| partially_completed | Some (but not all) the requested captures were captured. The order was partially fulfilled. |
Task captures
The previous section explained the task states and their relationship with planned and past captures.
But what is it a capture? What are planned captures and past captures?
A planned capture is a capture that we plan to take. It is the compromise of taking a capture on behalf of a task in the future.
A past capture occurred in the past, and it's being processed or already delivered to the client.
When a capture fails during any stage of the capturing, processing, and delivering process, it becomes a failed capture.
The capture status defines whether a task is planned, past, or failed.
| State | Description |
|---|---|
| queued | The capture is planned, and it will happen in the future. A capture in this state is considered a "planned capture". |
| failed | Something failed, and the image can not be delivered. The failure can be at any stage of the process: during camera command execution, file downloading, or image processing. It is possible that the image was delivered, but for some reason, it was not usable for the final client and they decided not to approve them. All captures in failed status will be re-planned as long as the task is active (inside the task period). |
| processing | The capture was taken and is being processed. This state covers the execution of the camera command up to the final image delivery, considering all the processing steps to generate that image. |
| published | The capture was delivered, and the final client approved it. A capture in published status is considered a success case to fulfill the task. |
The state of a planned capture is always queued. It's start date is always in the future, but under certain circumstances, it may happen that captures in status queued had a start date in the past. The reason is the lack of evidence that the satellite executed the capture as expected. The situation should be normalized within 24 hours of the capture start date.
A capture in processing or published status is a past capture, meaning it is useful to fulfill the order, is valuable for the client, or is still being processed.
Under any unexpected circumstances, if any failure happens during capture, processing, delivering, or if for any reason the capture is not valuable for the client, the status will be failed corresponding to a failed capture.
Tasking using the Objects In Space dedicated endpoint
OIS (Objects in space) is a type of product that allows capturing orbital targets (instead of land targets).
To create an OIS, first, you need to know the product ID corresponding with OIS. You also must ensure your user is allowed to use the product and use the /ois/ endpoint.
As opposed to other tasks types where the satellite executing the capture and the date and time where the capture will take place are given by the planning process, in OTS tasks you must specify several details, according to the type of maneuver that will be used to make the capture.
The regular way of making OIS is made with the spotlight method. This method requires two parameters: capture_at with the date and time of the capture to be made, and target, specifying the point.
We also provide support to use the evo stripe maneuver in OIS captures. This maneuver requires a start_point and a direction_point, as well as date and time to start the capture in the form of the parameter time_at_start_point and the expected ground_speed, expressed in km/s. We also accept an optional parameter of duration, which should be specified in seconds. All the points should be in GeoJSON format.
All of the parameters for the maneuver go in the field maneuver_params
There's another optional parameter (outside of maneuver parameters), called absolute_exposure, specified in microseconds, which allows to customize the exposure time of the image. Values for this parameter should be an integer number between 410 and 6000. Please only use this parameter if you know exactly the value.
Captures for OIS tasks can be obtained using the regular tasking API endpoints.