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 currently supports Point, Stereo and Area Tasking Orders. As we continue to improve our capabilities, we plan to support additional order types (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 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.

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 Progress while 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 Pending or In Progress, however captures already Queued, Processing or Published at 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.
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 elapses 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 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.

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 called exclusivity_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=PUBLISHED which will return all captures for the given tasking order that have been published
For each returned capture, take the date stored in the acquired_time field and add the number of exclusivity_days to it to find the date when that capture's exclusivity period will end. E.g. If the acquired_date is 2020-10-10T12:00:00 and the exclusivity_days value 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 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:

Overview