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 Tasking Orders
- Get the status of their order and check the collection progress
- View the metadata on the images tasked in attempting to fulfill their order
Automated Tasking currently supports Point, Strip, Stereo and Area Tasking Orders. As we continue to improve our capabilities, we plan to support additional order types (e.g. Video).
Key Concepts
Order: A request to obtain imagery of an 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 an 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 publication to the ordering customer and the SkySat Archive.
Capture Assessment: A representation of whether a capture meets the order’s specifications, thereby fulfilling an order.
Archive Publication Time Period: the time between when a capture is published to the customer who ordered the imagery and the published to the SkySat archive.
Tasking Order Status
After a Tasking Order has been entered, you may check the Tasking API for the status of that Tasking Order. The diagram below outlines how Tasking Orders flow through the system. N.B. This is applicable only to non locked-in Tasking Orders. For information on how Lock-In Tasking Order states, differ, refer to API reference
- Received: The Tasking Order has been entered into the system.
- Rejected: The Tasking Order could not be accepted due to it not passed feasibility checks, for example, tessellation if it is an area order
- Pending: The Tasking Order has been accepted but has not yet reached its start time
- IN_PROGRESS: The Tasking 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. Tasking Orders that have taken captures which did not meet specifications will stay in
IN_PROGRESSwhile they are re-tasked. - Fulfilled: The Tasking Order has a capture which meets fulfillment specifications.
- Cancelled: The Tasking 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.
Tasking 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_status_published_count": 0,
"capture_assessment_success_count": 0,
"capture_assessment_invalid_count": 0,
"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.
- Processing: The capture has been downlinked and is in our processing pipeline.
-
Published:
- Captures are published first to the customer who ordered the image. Only other users in this user’s organization may see this collect during this archive time period.
- After the Archive Time period has elapsed the imagery is published to all customers who have purchased the SkySat archive.
-
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 IN_PROGRESS 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.
Standard delivery & archive
An integral part of the Planet hi-res sevice is the concept of exclusive access to the captures that may be retrieved as part of a Tasking Order. When you create a tasking order, this exclusivity period will be applied to all captures that are produced as part of that tasking order, ensuring that only you have access to those captures for the duration of the exclusivity period. The standard duration for the exclusive access period is 30 days, after which time the captures will be moved into the public archive.
The Tasking Dashboard will display the date that an image will lose its exclusivity, but if you want to calculate this yourself or are an API user, this is possible using the following method:
- Retrieve the order via the
v2/orders/{order_id}endpoint. The reponse will include a field calledexclusivity_days, which indicate the exclusivity period for captures attributed to that tasking order - Then make a second call to
v2/captures/?order_id={order_id}&status=PUBLISHEDwhich will return all captures for the given tasking order that have been published - For each returned capture, take the date stored in the
acquired_timefield and add the number ofexclusivity_daysto it to find the date when that capture's exclusivity period will end. E.g. If theacquired_dateis 2020-10-10T12:00:00 and theexclusivity_daysvalue is 30, then the exclusivity period for that capture will end on 2020-11-09T12:00:00
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 IN_PROGRESS 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: