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.

• 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_PROGRESS while 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 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.

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 and archive¶

As part of Planet’s mission to make hi-res data more accessible and actionable, Tasking orders, by default, are automatically published to the SkySat Archive. However, if you have the “30-day SkySat Archive withhold” product, you can withhold orders from the SkySat Archive for up to 30 days.

If you have the “30-day SkySat Archive withhold” offering, you can request that your CSM set a number of days—up to 30—to withhold the data from the SkySat Archive. In the Order details view, you can see the number of days you’ve requested in the “Exclusivity days” field.

To derive the SkySat Archive publication date, add the number of exclusivity days to date of acquisition. If you want to calculate this from the API, take the following steps:

1. Retrieve the order via the v2/orders/{order_id} endpoint. The response includes a field called exclusivity_days, which indicates the exclusivity period for captures attributed to that tasking order.
2. Then make a second call to v2/captures/?order_id={order_id}&status=PUBLISHED, which returns all captures for the given tasking order that have been published.
3. 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 ends. For example, if the acquired_time 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. Note that acquired_time is always UTC.

Limits¶

In order to safely scale use of the Tasking API, 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¶

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: