Planet’s Tasking API is a programmatic interface that enables customers to manage and request imagery collection in an efficient and automated way. With the Tasking API, customers can:
- Create, edit, and cancel SkySat point collection orders
- Get the status of their order and check the collection progress
- View metadata on the images tasked in attempt to fulfill of their order
Automated Tasking is currently available for single SkySat point collections only. As we continue to improve our capabilities, we plan to support additional order types (area, stereo, video, bulk orders, etc.).
Key Concepts
Order: A request to obtain imagery of a single contiguous area of interest.
Order Status: A representation of where an order is at in its lifecycle – from creation and collection to order fulfillment.
Capture: An image which was tasked in attempt to fulfill an order. There is currently a one-to-many relationship between orders and captures, as an order may need to be tasked multiple times in order to meet cloud cover specifications or other fulfillment criteria. A given capture may or may not fulfill any order.
Capture Status: A representation of where a capture is at in its lifecycle – from uplink to satellite to publish in our catalog.
Capture Assessment: A representation of whether a capture meets the order’s specifications, thereby fulfilling an order.
Order Status
After an order has been entered, you may check the Tasking API for the status of that order. The diagram below outlines how orders flow through the system.
- Pending: The order has been accepted and its start time has not yet passed.
- In Progress: The order’s start time has passed and it is ready to be scheduled. Time in this state will depend on local cloud cover and collection capacity. Orders that have taken captures which did not meet specifications will stay in
In Progresswhile they are retasked. - Fulfilled: The order has a capture which meets fulfillment specifications.
- Cancelled: The order was cancelled. Orders may be cancelled if they are
PendingorIn Progress, however captures alreadyQueued,ProcessingorPublishedat the time of cancellation, may still be subject to charge (see Capture Status for details). - Expired: The order’s end time has passed, all of its captures have been
Published, and none meet specifications. The order will no longer be scheduled for imaging. - Failed: The order failed.
Order Status Example
To see the status of your order, you can make GET request for your order id. You can also filter orders by additional order metadata. See our API reference for more information.
Endpoint
https://api.planet.com/tasking/v2/orders/?status=FULFILLED
Response example
{
"id": "bfc45520-8a72-4d23-bfd1-7b22f23ed133",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-77.306467,
45.435827
],
[
-77.229787,
45.435827
],
[
-77.22975,
45.489812
],
[
-77.306504,
45.489812
],
[
-77.306467,
45.435827
]
]
]
},
"capture_count": 2,
"capture_status_queued_count": 0,
"capture_status_processing_count": 0,
"rank": 1,
"start_time": "2019-09-30T20:30:50.836516Z",
"end_time": "2020-09-27T23:59:59.999000Z",
"created_time": "2019-09-30T20:30:51.807703Z",
"name": "cairo_egypt",
"status": "FULFILLED"
}
Capture Status
As described under Key Concepts, an order may have multiple captures, as multiple collections may be required to acquire an image which meets your specifications (cloud cover, etc.).
Each capture of an order has a status, so that you may follow along with where that capture is at in its lifecycle to inform expectations on acquisition or when an image might be published. The diagram below outlines how captures flow through the system.
- Queued: The capture has been created and sent to a satellite. It will be imminently acquired and downlinked, typically within ~3 hrs.
- Processing: The capture has been downlinked and is in our processing pipeline.
- Published: The capture has been published to our catalog, typically around ~10 hours after processing starts.
- Failed: The capture has failed to be captured or failed in processing.
Capture Status Example
To see the status of your order’s captures, you can make a GET request for captures, filtering by order id(s). You can also filter by additional capture metadata. See our API reference for more information.
Endpoint
https://api.planet.com/tasking/v2/captures/?order_id=<order-id>
Response example
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "1e0268d2-8c96-49ed-b809-eceafa563950",
"assessment": "SUCCESS",
"updated_time": "2019-09-21T23:57:43.783444Z",
"acquired_time": "2019-09-21T08:51:31.094000Z",
"published_time": "2019-09-21T23:57:43.783444Z",
"status": "PUBLISHED",
"status_description": null,
"strip_id": "s104_20190921T085131Z",
"cloud_cover": 0.16,
"item_types": [
"SkySatScene",
"SkySatCollect"
]
}
]
}
Retasking & Assessment
If an order’s capture does not meet specifications, it will be retasked until its end time expires. Multiple captures may be collected for an order to satisfy its cloud cover and collection requirements. As captures are collected they are algorithmically assessed for cloud cover and may also be subject to another round of human-in-the-loop review.
A capture will be assessed as SUCCESS if cloud cover is less than or equal to your contractual cloud cover specifications. If a capture meets specifications, its order’s state will change from IN PROGRESS to FULFILLED.
A capture will be assessed as INVALID if cloud cover exceeds contractual specifications. If a capture is invalid, its order’s state will stay in REQUESTED and be retasked if its end time has not passed, or transition to EXPIRED if its end time has passed.
Note that as part of our human-in-the-loop review, a capture evaluated by the system may be manually reassessed, which may cause its order’s state to change. For example, a capture the system marked as SUCCESS may be manually reviewed as INVALID changing its order’s state from FULFILLED to IN PROGRESS (or EXPIRED). Similar order state changes would be expected for a capture marked INVALID which was manually reviewed as a SUCCESS. Typically any manual review happens within 24 hours of capture publish and changes to an order’s state due to manual assessment after this time are unlikely.
Limits
In order to safely scale use of the Tasking API in Beta, each organization using the Tasking API will have configurable system limits. Please check in with your Account Manager to confirm what your organization’s limits are.
Maximum active orders refer to the number of orders you may have in PENDING or REQUESTED states.
Maximum order duration may not exceed your contract duration or 1 year (whichever ends earlier).
Orders that are submitted which hit the maximum active order limit or exceed maximum order duration will return a 400 Bad Request response.
API Access
The Tasking API is currently in Beta. To determine whether you qualify for early access, please reach out to your Account Manager.
The Tasking API uses Basic HTTP Authentication and requires that you have a Planet API key. To read more about how to authenticate with the Tasking API, visit the Tasking Examples page for this and examples on how to create orders and much more.
Rate this guide: