Planet SDK for Python

The Planet SDK for Python provides a Python API and a Command-Line Interface (CLI) to interact with Planet APIs. The current version supports the following core workflows:

• Data: Search for imagery from the Planet data catalog.
• Orders: Process and download or deliver imagery.
• Subscriptions: Set up automated searches to process and deliver imagery.
• Features: Upload areas of interest to the Planet platform.
• Destinations: Create destinations for secure cloud credential storage.
• Mosaics: Describe, access, and download Mosaic products.

Future support is planned for Quota, Reports, Tasking, and services currently included in sentinelhub-py.

The auth command group is used to manage authorization credentials. You can list accounts, log in, or manage API keys.

Available Commands:

• list: List authorization accounts.
• login: Obtain and store authorization credentials.
• login-key: Obtain and store API key authorization credentials.
• print-key: Print the stored API key.

Usage: planet auth [OPTIONS] COMMAND [ARGS]...

  Commands for working with Planet authentication

Options:
  --help           Show this message and exit.

Commands:
  list       List authorization accounts
  login      Obtain and store authorization credentials
  login-key  Obtain and store api key authorization credentials
  print-key  Print the stored api key

The Planet CLI follows a standard command structure: planet [OPTIONS] COMMAND [ARGS].... The base command provides global options for controlling output and logging, and serves as the entry point for specialized command groups like auth, data, and orders.

Usage: `planet [OPTIONS] COMMAND [ARGS]...`

Planet Command Line Interface

Options:
  --verbosity [warning|info|debug|none]  Logging verbosity level.
  --quiet                              Disable all reporting.
  --version                            Show the version and exit.
  --help                               Show this message and exit.

Commands:
  auth    Commands for working with Planet authentication
  data    Commands for interacting with the Data API
  orders  Commands for interacting with the Orders API

The Planet SDK and CLI are low-level interfaces designed to mirror the core Planet APIs. There is a one-to-one match between SDK function calls and API endpoints.

In addition to direct API mapping, the SDK provides several built-in capabilities to simplify development:

• Retry logic: Automatic handling of transient request failures.
• Input pre-validation: Checking inputs before they are sent to the API.
• JSON Helpers: Functions to assist in creating JSON request arrays.
• State management: Handling internal state for requests.
• Pagination management: Automatically managing paged responses from the API.
• Checksum validation: Verifying file integrity during downloads.

The SDK and Planet CLI resolve authentication settings using the following priority order (from highest to lowest):

1. Explicit Arguments: Arguments passed directly to the planet.Auth class (in the SDK) or via the command line (in the CLI).
2. Environment Variables: Variables set in the system environment. Note: Environment variables override configuration saved by the planet CLI.
3. Configuration Files: The .planet.json file and files within the .planet directory in the user's home directory (managed via planet auth profile).
4. Built-in Defaults: The fallback values used if no other configuration is found.

The Planet SDK uses a structured exception hierarchy to distinguish between client-side issues and server-side errors. All exceptions in the SDK inherit from the base class PlanetError.

• PlanetError: The base exception for all SDK errors.
• ClientError: Raised for all client-side exceptions (e.g., issues with request construction or local validation).
• APIError: The base class for all server-side errors. These are raised based on HTTP status codes and contain the unedited error message returned by the server.

When using the SDK or API, be aware of the following operational constraints:

• Order Retention: Order records are kept for 90 days. To retrieve older orders, you must contact Planet support.
• Cost and Quotas: SDK calls hit your account quotas exactly like direct API calls. Be mindful of batch or bulk routines that might inadvertently incur higher costs.

In Version 2, all API communication is managed through a Session object. The Session handles connection pooling, authentication, and manages HTTP connections. Each specific API (e.g., Orders, Data) requires a client instance that is initialized with this session.

You can instantiate specific clients directly or use the session.client() convenience method.

Note: Because V2 is asynchronous, you must use async with to manage the session lifecycle.

from planet import OrdersClient, Session

async def main():
    async with Session() as session:
        # Option 1: Direct instantiation
        client = OrdersClient(session)
        
        # Option 2: Using the session convenience method
        client = session.client('orders')
        
        result = await client.create_order(order)