At Planet, we offer a wide range of documented examples for using our APIs, covering a myriad of use cases. However, it's common to find that these examples do not exactly match what is needed, leading to a patchwork of snippets gathered from various sources such as GitHub notebooks, Community comments, support channels, or custom solutions provided by the Professional Services team.

When working with the Subscription and Orders APIs, there are many examples available to assist with specific use cases. While these APIs share similarities, important differences must be understood to avoid potential pitfalls. Mixing examples from different sources can make it challenging to trace the origin of each snippet.

Key Differences Between the Subscription and Orders APIs

The following outlines the primary differences between the Subscription and Orders APIs, focusing on common parameters, necessary adjustments, and non-interchangeable aspects.

1. Tool Support in Both APIs

• The Subscription-API provides support for a range of tools designed to handle various data processing tasks. These tools include:
       - harmonize, toar, clip, reproject, bandmath, cloud_filter, file_format
• The Orders-API offers a slightly different set of tools, including:
       - harmonize, toar, clip, reproject, bandmath, file_format, composite, coregister, tile
  
  

2. Design Intention and Workflow

The Orders API was designed with the assumption that users will review layouts before placing an order. This is why it includes composite tools and the subscription cloud_filter options, and why scenes are automatically arranged with the latest one on top for user review.

In contrast, the Subscription API delivers scenes daily without user inspection, making it more challenging to manage a potential composite, but appealing to have a cloud filter options.

Additionally, the Orders API supports basemaps, while the Subscription API does not.

3. Differences in Schema

In both APIs, tools is an array of objects. However, these objects are different. The harmonize tool in Subscription-API uses this structure:

{
    "type": "harmonize",
    "parameters": {
      "target_sensor": "Sentinel-2"
    }
 }

While in Orders-API, the format should be structured as follows:

 {
    "harmonize": {
      "target_sensor": "Sentinel-2"
    }
 }

Note that In Orders-API, the top-level key directly represents the type of operation, and as consequence, it is more concise and can be easier to handle.  On the other hand, the way it was designed in Subscription-API enhances readability and maintainability because each part of the JSON payload has a specific role. Developers can quickly understand what operation is being requested and what parameters are needed.

4. Data-API does not Accept tools array

When searching for images with the Data API, you might reuse previous payload examples from Orders or Subscription APIs. While the cloud_filter is a tool for filtering assets, you can achieve similar results in the Data API with a Field Filter configuration.