Planet SDK for Python

https://planet-sdk-for-python-v2.readthedocs.io
Admin
A Python library for discovering and retrieving earth observation data from Planet Labs PBC. It...
Tokens:71,771
Snippets:324
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Planet SDK for Python

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/quick-start-guide

Installs the Planet SDK for Python from PyPI using pip. Ensure you have Python 3.9 or greater and a virtual environment set up.

```bash
pip install planet
```

--------------------------------

### Install Planet Python SDK

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Installs the Planet Python SDK using pip, the Python package installer. This command is essential for setting up the SDK in your Python environment.

```bash
pip install planet

```

--------------------------------

### Install Planet Python SDK

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Installs the Planet SDK for Python using pip. This is the first step to begin using the SDK in your Python projects.

```bash
pip install planet
```

--------------------------------

### Features API: Create, List Collections and Items

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Provides Python code examples for interacting with the Planet Features API. This includes creating a new feature collection, listing all available collections, and listing items (features) within a specific collection.

```python
# Create a new feature collection
# new_collection = pl.features.create_collection(title="my collection", description="a new collection")

# List all collections
# collections = pl.features.list_collections()
# for collection in collections:
#   print(collection)

# List items/features in a collection (replace collection_id with an actual ID)
# collection_id = "your_collection_id"
# items = pl.features.list_items(collection_id)
# for item in items:
#   print(item)

# Note: Actual calls are commented out to prevent unintended operations.
# Ensure 'pl' is imported and collection_id is valid before uncommenting.

```

--------------------------------

### Install Planet SDK for Python

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-guide

Installs the Planet SDK for Python using pip, the Python package installer. This command ensures you have the necessary tools to interact with Planet's APIs from your command line.

```bash
pip install planet
```

--------------------------------

### Python SDK Examples

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/resources

Collection of Python scripts and notebooks demonstrating how to use the Planet SDK for various tasks. These examples cover ordering, activating, and downloading assets, as well as preparing Analysis Ready Data (ARD).

```Python
# Example: data_download_multiple_assets.py
# Orders, activates, and downloads two assets.
# See: https://github.com/planetlabs/planet-client-python/blob/main/examples/data_download_multiple_assets.py
```

```Python
# Example: orders_create_and_download_multiple_orders.py
# Creates two orders, each with unique Area of Interest (AoI).
# See: https://github.com/planetlabs/planet-client-python/blob/main/examples/orders_create_and_download_multiple_orders.py
```

```Python
# Example: Planet API Python Client Notebook
# Introduces Planet's Data API and the 'planet' module.
# See: https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/Data-API/planet_python_client_introduction.ipynb
```

```Python
# Example: Orders API & Planet SDK Demo Notebook
# Demonstrates getting started with the Planet SDK and the Orders API.
# See: https://github.com/planetlabs/notebooks/blob/665f165e59f2c3584976ad2dde569c649e631c0b/jupyter-notebooks/orders_api_tutorials/Planet_SDK_Orders_demo.ipynb
```

```Python
# Example: Analysis Ready Data Tutorial Part 1
# Introduction and best practices for preparing Analysis Ready Data using the SDK.
# See: https://github.com/planetlabs/notebooks/blob/6cc220ff6db246353af4798be219ee1fe7e858b0/jupyter-notebooks/analysis-ready-data/ard_1_intro_and_best_practices.ipynb
```

```Python
# Example: Analysis Ready Data Tutorial Part 2
# Use case 1: Prepare an NDVI time stack using the SDK's 'order_request' feature.
# Use case 2: Visualize the NDVI imagery.
# See: https://github.com/planetlabs/notebooks/blob/6cc220ff6db246353af4798be219ee1fe7e858b0/jupyter-notebooks/analysis-ready-data/ard_2_use_case_1.ipynb
```

--------------------------------

### Place and Download Order

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Guides on placing an order for multiple assets using the Orders API client. It covers building an order request with `order_request`, creating the order, waiting for its completion, and downloading the ordered assets.

```python
from planet import Planet, order_request

def main():
    pl = Planet()
    image_ids = ["20200925_161029_69_2223"]
    request = order_request.build_request(
        name='test_order',
        products=[
           order_request.product(
               item_ids=image_ids,
               product_bundle='analytic_8b_udm2',
               item_type='PSScene',
               fallback_bundle='analytic_udm2,analytic_3b_udm2')
       ]
    )

    order = pl.orders.create_order(request)

    # wait for the order to be ready
    # note: this may take several minutes.
    pl.orders.wait(order['id'])

    pl.orders.download_order(order['id'], overwrite=True)

# main()

```

--------------------------------

### Initialize Data Client Session

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Demonstrates setting up an asynchronous session with the Planet Data Client to perform operations. This is the foundational step for most data-related tasks.

```Python
async def main():
    async with Session() as sess:
        client = sess.client('data')
        # perform operations here

asyncio.run(main())
```

--------------------------------

### Install Planet SDK v1

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/venv-tutorial

Installs the Planet SDK version 1 using pip.

```shell
pip install planet
```

--------------------------------

### Install Python 3 with Homebrew

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/venv-tutorial

Installs Python 3 using Homebrew, making the 'python3' command available.

```shell
brew install python
```

--------------------------------

### Launch Mapshaper GUI

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-tips-tricks

Starts the Mapshaper graphical user interface for interactive simplification of GeoJSON files.

```shell
mapshaper-gui skysat-large.geojson
```

--------------------------------

### Set Planet API Key Environment Variable

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/quick-start-guide

Sets the Planet API key as an environment variable for authentication. This is the primary method for authenticating with the Planet API for the SDK. For other options, consult the SDK guide.

```bash
export PL_API_KEY=your_api_key
```

--------------------------------

### Create a Planet SDK session using context manager

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

This snippet illustrates the recommended way to create a `Session` object for interacting with Planet services. It utilizes an asynchronous context manager (`async with Session()`) which automatically handles session setup and cleanup, ensuring resources are properly managed.

```python
import asyncio
import os
from planet import Session

async def main():
    async with Session() as sess:
        # perform operations here
        pass

asyncio.run(main())
```

--------------------------------

### Create, Wait, and Download Order with Progress Tracking

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Demonstrates creating an order, waiting for its processing with progress updates using a callback, and then downloading the order. It leverages the `planet.reporting.StateBar` for visual progress indication during the waiting phase.

```python
from planet import reporting
import asyncio

# Assuming Session, create_request, and DOWNLOAD_DIR are defined elsewhere
# from planet import Session
# def create_request(): ...
# DOWNLOAD_DIR = "./downloads"

async def create_and_download(client, order_detail, directory):
   with planet.reporting.StateBar(state='creating') as reporter:
       order = await client.create_order(order_detail)
       reporter.update(state='created', order_id=order['id'])
       await client.wait(order['id'], callback=reporter.update_state)

   await client.download_order(order['id'], directory, progress_bar=True)

async def main():
   async with planet.Session() as sess:
       cl = sess.client('orders')

       # Create the order request
       request = create_request()

       # Create and download the order
       order = await create_and_download(cl, request, DOWNLOAD_DIR)

# To run the main function:
# asyncio.run(main())

```

--------------------------------

### Planet SDK for Python Contribution Guide

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/resources

Information on how to contribute to the Planet SDK for Python project. This includes guidelines for development, issue reporting, and pull requests.

```Markdown
# Contributing to Planet SDK for Python

To contribute or develop with this library, see the CONTRIBUTING guide.

Link: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md
```

--------------------------------

### Initialize Planet Client in Python

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/quick-start-guide

Initializes the main `Planet` client class, which automatically detects the `PL_API_KEY` environment variable for authentication. This client provides access to Data, Orders, and Subscriptions APIs.

```python
from planet import Planet
pl = Planet()  # automatically detects PL_API_KEY
```

--------------------------------

### Create and manually close a Planet SDK session

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

This example demonstrates how to create a `Session` object and manually manage its lifecycle. It shows explicit session creation and closing using `await sess.aclose()`, which is useful when a session needs to be reused across multiple asynchronous operations.

```python
async def main():
    sess = Session()
    # perform operations here
    await sess.aclose()

asyncio.run(main())
```

--------------------------------

### StateBar Usage Example

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Example demonstrating how to use the `StateBar` from the `planet.reporting` module to track and update the state of an order during processing. It utilizes a context manager for initialization and cleanup.

```python
from planet import reporting

with reporting.StateBar(state='creating') as bar:
    bar.update(state='created', order_id='oid')
    ...
```

--------------------------------

### Install Homebrew

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/venv-tutorial

Installs Homebrew, a package manager for macOS, which is used to install Python.

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Authenticate using custom environment variable and create async session

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

This example shows how to authenticate by reading credentials from a custom environment variable using `Auth.from_env`. It then sets up an asynchronous session using this authentication object within an `async with` block for managed resource cleanup.

```python
import asyncio
import os
from planet import Auth, Session

auth = Auth.from_env('ALTERNATE_VAR')
async def main():
    async with Session(auth=auth) as sess:
        # perform operations here
        pass

asyncio.run(main())
```

--------------------------------

### Cloud Delivery Configuration Example

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-orders

An example JSON configuration for delivering order results directly to a cloud storage bucket, such as AWS S3. It specifies authentication credentials, bucket name, region, and archive type.

```json
{
    "amazon_s3": {
        "aws_access_key_id": "aws_access_key_id",
        "aws_secret_access_key": "aws_secret_access_key",
        "bucket": "bucket",
        "aws_region": "aws_region"
    },
    "archive_type": "zip"
}

```

--------------------------------

### Planet CLI: Subscription Request with Sentinel Hub Hosting

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions

Example of using the 'planet subscriptions request' command with the --hosting flag to specify Sentinel Hub as the hosting provider for the subscription.

```bash
planet subscriptions request \
    --name 'First Subscription' \
    --source request-catalog.json \
    --tools tools.json \
    --hosting sentinel_hub \
    | planet subscriptions create -
```

--------------------------------

### Download and Validate Asset

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Details the process of activating, waiting for, downloading, and validating a Planet asset using the Data Client. It includes callbacks for progress reporting during activation.

```Python
async def download_and_validate():
    async with Session() as sess:
        cl = sess.client('data')

        # get asset description
        item_type_id = 'PSScene'
        item_id = '20221003_002705_38_2461'
        asset_type_id = 'ortho_analytic_4b'
        asset = await cl.get_asset(item_type_id, item_id, asset_type_id)

        # activate asset
        await cl.activate_asset(asset)

        # wait for asset to become active
        asset = await cl.wait_asset(asset, callback=print)

        # download asset
        path = await cl.download_asset(asset)

        # validate download file
        cl.validate_checksum(asset, path)
```

--------------------------------

### Create Planet Order with OrdersClient

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Demonstrates how to create an order using the Planet SDK's OrdersClient. It involves establishing a session, obtaining the 'orders' client, and calling the 'create_order' method with a pre-built request object.

```python
async def main():
    # Create a session and client
    # The Orders API client is also a subclass of the Session
    # class, so it has all the same methods.
    async with planet.Session() as sess:

        # 'orders' is the service name for the Orders API.
        cl = sess.client('orders')

        request = create_request() # Assuming create_request() is defined as above
        order = await cl.create_order(request)
```

--------------------------------

### Search Multiple Scene Types and Pipe to Kepler.gl

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-tips-tricks

This example searches for multiple types of Planet scenes (PSScene, Sentinel2L1C, Landsat8L1G, SkySatCollect, Sentinel1) with sorting and a limit, then pipes the results to kepler for visualization. It requires the MAPBOX_API_KEY environment variable.

```shell
curl -s https://storage.googleapis.com/open-geodata/ch/vermont.json \
| planet data filter --geom - \
| planet data search PSScene,Sentinel2L1C,Landsat8L1G,SkySatCollect,Sentinel1 \
--sort 'acquired desc' --limit 1500 --filter - \
| kepler
```

--------------------------------

### Planet SDK Subscription Tools Configuration

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions

Example JSON structure for defining multiple processing tools to be applied to a Planet subscription. Each tool has a 'type' and 'parameters' object specifying its configuration.

```json
[
    {
        "type": "toar",
        "parameters":
        {
            "scale_factor": 10000
        }
    },
    {
        "type": "reproject",
        "parameters":
        {
            "projection": "WGS84",
            "kernel": "cubic"
        }
    },
    {
        "type": "harmonize",
        "parameters":
        {
            "target_sensor": "Sentinel-2"
        }
    },
    {
        "type": "file_format",
        "parameters":
        {
            "format": "COG"
        }
    }
]
```

--------------------------------

### Python Example: Using SubscriptionsClient

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Demonstrates how to initialize and use the SubscriptionsClient asynchronously within a Planet SDK session. It shows the basic structure for interacting with the subscriptions API, including session management and client instantiation.

```python
import asyncio
from planet import Session

async def main():
    async with Session() as sess:
        cl = sess.client('subscriptions')
        # use client here

asyncio.run(main())
```

--------------------------------

### Get Specific Asset Details using CLI

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Retrieves detailed information about a particular asset for an item, such as its status and download availability. This is useful for checking the readiness of a specific data product.

```cli
planet data asset-get PSScene 20230310_083933_71_2431 ortho_analytic_8b
```

--------------------------------

### Planet DataClient API Reference

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Comprehensive API documentation for the DataClient, detailing methods for interacting with Planet's data services. Includes parameters, return values, exceptions, and usage examples.

```APIDOC
DataClient (_BaseClient)
  High-level asynchronous access to Planet's data API.

  activate_asset(self, asset)
    Activate an item asset.
    Parameters:
      asset (dict): Description of the asset. Obtained from get_asset().
    Exceptions:
      planet.exceptions.APIError: On API error.
      planet.exceptions.ClientError: If asset description is not valid.

  create_search(self, item_types, search_filter, name, enable_email=False, geometry=None)
    Create a new saved structured item search.
    To filter to items you have access to download which are of standard (aka not test) quality, use the following:
    ```python
    from planet import data_filter
    data_filter.and_filter([
        data_filter.permission_filter(),
        data_filter.std_quality_filter()
    ])
    ```
    To avoid filtering out any imagery, supply a blank AndFilter, which can be created with `data_filter.and_filter([])`.
    Parameters:
      item_types (List[str]): The item types to include in the search.
      search_filter (dict): Structured search criteria.
      name (str): The name of the saved search.
      enable_email (bool): Send a daily email when new results are added. (Default: False)
      geometry (Union[dict, str]): A feature reference or a GeoJSON (Default: None)
    Returns:
      dict: Description of the saved search.
    Exceptions:
      planet.exceptions.APIError: On API error.

  delete_search(self, search_id)
    Delete an existing saved search.
    Parameters:
      search_id (str): Saved search identifier.
    Exceptions:
      planet.exceptions.APIError: On API error.

  download_asset(self, asset, filename=None, directory=PosixPath('.'), overwrite=False, progress_bar=True)
    Download an asset.
    The asset must be active before it can be downloaded. This can be achieved with activate_asset() followed by wait_asset().
    If overwrite is False and the file already exists, download will be skipped and the file path will be returned as usual.
    Parameters:
      asset (dict): Description of the asset. Obtained from get_asset() or wait_asset().
      filename (Optional[str]): Custom name to assign to downloaded file. (Default: None)
      directory (Path): Base directory for file download. (Default: PosixPath('.'))
      overwrite (bool): Overwrite any existing files. (Default: False)
      progress_bar (bool): Show progress bar during download. (Default: True)
    Returns:
      Path: Path to downloaded file.
    Exceptions:
      planet.exceptions.APIError: On API error.
      planet.exceptions.ClientError: If asset is not active or asset description is not valid.

  get_asset(self, item_type_id, item_id, asset_type_id)
    Get an item asset description.
    Parameters:
      item_type_id (str): Item type identifier.
      item_id (str): Item identifier.
      asset_type_id (str): Asset type identifier.
    Returns:
      dict: Description of the asset.
    Exceptions:
      planet.exceptions.APIError: On API error.
      planet.exceptions.ClientError: If asset type identifier is not valid.
```

--------------------------------

### Initialize Planet Client

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Initializes the main Planet client object, which serves as the entry point to interact with various Planet APIs like Data, Orders, and Subscriptions. It automatically detects the PL_API_KEY environment variable for authentication.

```python
from planet import Planet
pl = Planet()  # automatically detects PL_API_KEY
```

--------------------------------

### Download and Validate Asset

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Details the multi-step process of downloading a single asset: activating it, waiting for activation, downloading the file, and validating its integrity using checksums. It includes callback support for progress tracking during waiting.

```python
from planet import Planet

def download_and_validate():
    pl = Planet()

    # get asset description
    item_type_id = 'PSScene'
    item_id = '20221003_002705_38_2461'
    asset_type_id = 'ortho_analytic_4b'
    asset = pl.data.get_asset(item_type_id, item_id, asset_type_id)

    # activate asset
    pl.data.activate_asset(asset)

    # wait for asset to become active
    asset = pl.data.wait_asset(asset, callback=print)

    # download asset
    path = pl.data.download_asset(asset)

    # validate download file
    pl.data.validate_checksum(asset, path)

# download_and_validate()

```

--------------------------------

### Get Item Details using CLI

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Retrieves detailed information about a specific item by its Type and ID. This command is essential for examining individual data products.

```cli
planet data item-get PSScene 20230310_083933_71_2431
```

--------------------------------

### Planet CLI Authentication Commands

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-guide

Commands to initialize authentication with the Planet CLI and retrieve your API key. These commands facilitate access to Planet services by verifying your account credentials.

```shell
$ planet auth init

```

```shell
Initialized

```

```shell
planet auth value

```

--------------------------------

### Filter by Permission and Standard Quality

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Applies filters for user permissions and standard data quality. This example also filters by a specific asset and pipes results to a search command.

```bash
planet data filter --permission --std-quality --asset ortho_analytic_8b_sr \
    | planet data search PSScene --filter -
```

--------------------------------

### Get Statistics by Interval

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Uses the 'stats' command to count items matching filters, binned by a specified time interval. This example counts items per day within a specific strip.

```bash
planet data filter --string-in strip_id 5743640 \
    | planet data stats PSScene --interval day --filter -
```

--------------------------------

### Check Planet SDK for Python Version

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-guide

Verifies the installed version of the Planet SDK for Python. This command is useful for ensuring you are running the latest version or a specific version required for certain functionalities.

```bash
planet --version
```

--------------------------------

### Basic DataClient Initialization

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Demonstrates how to initialize the Planet SDK's DataClient asynchronously. It shows importing necessary modules, creating a session, and obtaining the data client instance for subsequent operations.

```python
import asyncio
from planet import Session

async def main():
    async with Session() as sess:
        cl = sess.client('data')
        # use client here

asyncio.run(main())
```

--------------------------------

### Create, Wait, and Download in One Sequence

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-orders

A consolidated command sequence to create an order, wait for its completion, and then download the results.

```APIDOC
id=`planet orders create request-1.json | jq -r '.id'` && \
    planet orders wait $id && \
    planet orders download $id

  This chained command first captures the new order's ID, then waits for it to be ready, and finally downloads it.
```

--------------------------------

### Create Order with Hosting and Configuration Options

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-orders

Creates a Planet order with specific hosting providers (e.g., Sentinel Hub) and collection IDs, or requests configuration creation.

```APIDOC
planet orders create <request_file> --hosting <provider> [--collection-id <id>] [--create-configuration]

  Creates an order with advanced options.
  Parameters:
    request_file: Path to the JSON file containing order request details.
    --hosting <provider>: Specifies the hosting provider (e.g., 'sentinel_hub').
    --collection-id <id>: The ID of the collection to use with the hosting provider.
    --create-configuration: Flag to create a configuration for the order.
  Example:
    planet orders create request-1.json \
        --hosting sentinel_hub \
        --collection-id ba8f7274-aacc-425e-8a38-e21517bfbeff

    planet orders create request-1.json \
        --hosting sentinel_hub \
        --create-configuration
```

--------------------------------

### Geometry GeoJSON Example

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions

An example of a GeoJSON structure representing a polygon, used for defining spatial boundaries in subscription requests.

```json
{
    "coordinates":
    [
        [
            [
                139.5648193359375,
                35.42374884923695
            ],
            [
                140.1031494140625,
                35.42374884923695
            ],
            [
                140.1031494140625,
                35.77102915686019
            ],
            [
                139.5648193359375,
                35.77102915686019
            ],
            [
                139.5648193359375,
                35.42374884923695
            ]
        ]
    ],
    "type": "Polygon"
}
```

--------------------------------

### Planet CLI: Advanced Data Ordering and Processing

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-orders

Demonstrates advanced CLI workflows combining data filtering, searching, and order creation. Includes ordering the latest SkySat image and ordering multiple cloud-free PSScenes clipped to a geometry.

```bash
# Order the latest SkySat image
latest_id=$(planet data filter \
    | planet data search SkySatCollect \
        --sort 'acquired desc' \
        --limit 1 \
        --filter - \
    | jq -r .id)

planet orders request \
    --item-type SkySatCollect \
    --bundle analytic \
    --name 'SkySat Latest' \
    $latest_id \
    | planet orders create -

# Order 5 latest cloud-free PSScenes clipped to an area
ids=$(planet data filter --geom geometry.geojson --range clear_percent gt 90 \
    | planet data search PSScene --limit 5 --filter - \
    | jq -r .id \
    | tr '\n' ',' \
    | sed 's/.$//')

planet orders request \
    --item-type PSScene \
    --bundle analytic_sr_udm2 \
    --name 'Clipped Scenes' \
    $ids \
    --clip geometry.geojson \
    | planet orders create -
```

--------------------------------

### Check Planet SDK v1 Version

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/venv-tutorial

Verifies the installed version of the Planet SDK v1.

```shell
planet --version
```

--------------------------------

### Visualize Placemark Features with Planet CLI and Kepler.gl

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-tips-tricks

Shows how to fetch features from Placemark, filter them by geometry using the Planet CLI, search for relevant Planet scenes, and pipe the results to kepler for visualization. Requires MAPBOX_API_KEY.

```shell
curl -s https://api.placemark.io/api/v1/map/a0BWUEErqU9A1EDHZWHez/feature/91a07390-0652-11ed-8fdd-15633e4f8f01 \
| planet data filter --geom - \
| planet data search PSScene,Landsat8L1G,SkySatCollect,Sentinel1 --filter - | kepler
```

--------------------------------

### List Features API Collections

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Shows how to retrieve a list of all available collections in the Features API. The results are iterated asynchronously.

```Python
async with Session() as sess:
  client = FeaturesClient(sess)
  collections = client.list_collections()
  async for collection in collections:
    print(collection)
```

--------------------------------

### Get Subscription Details

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Retrieves a description of a specific subscription using its ID. Handles API and client errors.

```APIDOC
APIDOC:
method: get_subscription
description: Get a description of a Subscription.
parameters:
  - name: subscription_id
    type: str
    description: id of a subscription.
    required: true
returns:
  type: dict
  description: description of the subscription.
exceptions:
  - type: APIError
    description: on an API server error.
  - type: ClientError
    description: on a client error.
```

--------------------------------

### Filter by Multiple Assets

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Searches for data that includes multiple specified assets, for example, 'ortho_analytic_8b_sr' and 'udm2'. Results are piped to a search command.

```bash
planet data filter --asset ortho_analytic_8b_sr --asset udm2 \
    | planet data search PSScene --filter -
```

--------------------------------

### List Available Assets for an Item using CLI

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Displays all available assets for a specific item, including their status and any activation requirements. This helps in understanding the data products associated with an item.

```cli
planet data asset-list PSScene 20230310_083933_71_2431
```

--------------------------------

### List Features/Items in a Collection

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Demonstrates how to list all features (items) within a specified Features API collection. The items are retrieved and processed asynchronously.

```Python
async with Session() as sess:
  client = FeaturesClient(sess)
  items = client.list_items(collection_id)
  async for item in items:
    print(items)
```

--------------------------------

### Activate an Asset using CLI

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Initiates the activation process for a specific asset of an item, making it available for download. This is a prerequisite for downloading data via the Data API or CLI.

```cli
planet data asset-activate PSScene 20230310_083933_71_2431 ortho_udm2
```

--------------------------------

### Get Subscription Summary

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Summarizes the status of results for a single subscription. Returns totals by status. Handles API and client errors.

```APIDOC
APIDOC:
method: get_subscription_summary
description: Summarize the status of results for a single subscription via GET.
parameters:
  - name: subscription_id
    type: str
    description: ID of the subscription to summarize.
    required: true
returns:
  type: dict
  description: result totals for the provided subscription by status.
exceptions:
  - type: APIError
    description: on an API server error.
  - type: ClientError
    description: on a client error.
```

--------------------------------

### Get All Subscriptions Summary

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Summarizes the status of all subscriptions. Returns overall subscription totals by status. Handles API and client errors.

```APIDOC
APIDOC:
method: get_summary
description: Summarize the status of all subscriptions via GET.
returns:
  type: dict
  description: subscription totals by status.
exceptions:
  - type: APIError
    description: on an API server error.
  - type: ClientError
    description: on a client error.
```

--------------------------------

### List Subscriptions with Filtering

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions

Demonstrates how to list Planet subscriptions and apply various filters. Filters can be applied to creation time, end time, hosting status, name, source type, and subscription status. Datetime arguments support specific dates or intervals.

```bash
planet subscriptions list --status running
planet subscriptions list --source-type catalog
planet subscriptions list --created 2024-01-01T00:00:00Z/2025-01-01T00:00:00Z
planet subscriptions list --end-time 2025-01-01T00:00:00Z/..
planet subscriptions list --hosting true
```

--------------------------------

### Search Planet Catalog

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Demonstrates how to search for items in the Planet catalog using the `data.search()` method. It returns an iterator yielding search results.

```python
from planet import Planet

pl = Planet()
for item in pl.data.search(['PSScene'], limit=5):
    print(item)

```

--------------------------------

### Search Data Catalog with Filter

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Executes a search query against the data catalog using a pre-defined filter within an asynchronous session. It iterates through the results asynchronously.

```Python
async def main():
    async with Session() as sess:
        cl = sess.client('data')
        items = [i async for i in cl.search(['PSScene'], sfilter)]

asyncio.run(main())
```

--------------------------------

### Use asyncio to order Planet data with Session

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Demonstrates ordering Planet data asynchronously using Python's `asyncio` library and the Planet SDK. It emphasizes creating a `planet.Session` as a context manager for rate-limited operations and managing multiple concurrent data orders.

```python
import asyncio
import os

import planet

# Assume create_requests() and create_and_download() are defined elsewhere
# For example:
# def create_requests():
#     # Returns a list of request objects
#     pass
# async def create_and_download(client, request, download_dir):
#     # Creates and downloads an order
#     pass

DOWNLOAD_DIR = "./downloads"

async def main():
    async with planet.Session() as sess:
        client = sess.client('orders')

        requests = create_requests()

        await asyncio.gather(*[
            create_and_download(client, request, DOWNLOAD_DIR)
            for request in requests
        ])

if __name__ == '__main__':
    asyncio.run(main())
```

--------------------------------

### Post Search Results to GitHub Gist

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-tips-tricks

Demonstrates using the `gh cli` tool to create a GitHub Gist from Planet SDK search results. The output is piped through `planet collect` and `jq` before being uploaded as a GeoJSON file, providing a shareable and persistent visualization link.

```bash
planet data search SkySatCollect --sort 'acquired desc' --limit 1 \
| planet collect - | jq | gh gist create -f latest-skysat.geojson -w
```

```bash
planet data filter --string-in strip_id 5743640 | planet data search PSScene --filter - \
| planet collect - | gh gist create -f ps-search.geojson -w
```

--------------------------------

### SubscriptionsClient: Get Results

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-reference

Iterates over the results of a subscription, allowing filtering by status and limiting the number of results. This method yields descriptions of subscription results.

```APIDOC
SubscriptionsClient:
  get_results(self, subscription_id, status=None, limit=100)
    Iterate over results of a Subscription.
    Parameters:
      subscription_id (str): id of a subscription.
      status (Set[str]): pass result with status in this set, filter out results with status not in this set. Defaults to None.
      limit (int): limit the number of subscriptions in the results. When set to 0, no maximum is applied. Defaults to 100.
    Yields:
      dict: description of a subscription results.
    Exceptions:
      APIError: on an API server error.
      ClientError: on a client error.
    
```

--------------------------------

### Python SDK v2: Async Search Example

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/upgrading

Demonstrates how to use asynchronous methods in the Planet SDK v2. It shows setting up an async session, creating a data client, and performing a search with date and cloud cover filters using async iteration. This pattern is required for all client operations in v2.

```python
import asyncio
from datetime import datetime
from planet import Session
from planet import data_filter as filters

async def do_search():
    async with Session() as session:
        client = session.client('data')
        date_filter = filters.date_range_filter('acquired', gte=datetime.fromisoformat("2022-11-18"), lte=datetime.fromisoformat("2022-11-21"))
        cloud_filter = filters.range_filter('cloud_cover', lte=0.1)
        download_filter = filters.permission_filter()
        return [item async for item in client.search(["PSScene"], filters.and_filter([date_filter, cloud_filter, download_filter]))]

items = asyncio.run(do_search())

```

--------------------------------

### Request Catalog with Publishing Stages

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions

Demonstrates how to specify temporal filtering by acquisition or publication time using `--time-range-type` and control imagery availability with `--publishing-stage`. This example requests finalized imagery acquired on a specific date.

```bash
planet subscriptions request-catalog \
    --item-types PSScene \
    --asset-types ortho_analytic_8b \
    --geometry geometry.geojson \
    --start-time 2022-08-24T00:00:00-07:00 \
    --time-range-type acquired \
    --publishing-stage finalized \
    --filter filter.json
```

--------------------------------

### Search by Geometry

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Shows how to filter search results by spatial geometry using the `geometry` parameter in the `data.search()` method. This allows for location-based filtering of catalog items.

```python
from planet import Planet

geom = {
  "coordinates": [
    [
      [
        -125.41267816101056,
        46.38901501783491
      ],
      [
        -125.41267816101056,
        41.101114161051015
      ],
      [
        -115.51426167332103,
        41.101114161051015
      ],
      [
        -115.51426167332103,
        46.38901501783491
      ],
      [
        -125.41267816101056,
        46.38901501783491
      ]
    ]
  ],
  "type": "Polygon"
}

pl = Planet()
for item in pl.data.search(['PSScene'], geometry=geom, limit=5):
    print(item)

```

--------------------------------

### Get Order Information

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-orders

Retrieves detailed information about a specific order using its unique identifier. This command provides details such as download locations.

```bash
planet orders get 782b414e-4e34-4f31-86f4-5b757bd062d7
```

--------------------------------

### Get Yearly Statistics with GeoJSON Filter

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Calculates yearly statistics for scenes within a geographic area defined by a GeoJSON file. The results are piped to 'jq' for formatting.

```bash
curl -s https://raw.githubusercontent.com/ropensci/geojsonio/main/inst/examples/california.geojson \
    | planet data filter --geom - \
    | planet data stats PSScene --interval year --filter - \
    | jq
```

--------------------------------

### Pipe Planet SDK Search to jq for Console Output

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Demonstrates piping the output of `planet data search` to `jq` for formatted and syntax-highlighted display directly on the console. This combines the search functionality with `jq`'s enhanced output capabilities.

```shell
planet data search PSScene --filter filter.json | jq
```

--------------------------------

### Check Python Version

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/venv-tutorial

Use this command in your terminal to verify the currently installed Python version. This is a prerequisite for using the venv module, which requires Python 3.3 or higher.

```Shell
$ python --version

```

--------------------------------

### Filter by String-In (Multiple)

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-data

Filters data by multiple string values for a property, separated by commas. This example searches for instruments 'PS2' or 'PSB.SD'. Results are piped to a search command.

```bash
planet data filter --string-in instrument PS2,PSB.SD \
    | planet data search PSScene --filter -
```

--------------------------------

### Planet CLI: Create Subscription Request

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions

Command to construct a subscription request using separate JSON files for catalog source, tools, and delivery, then piping the output to create a new subscription.

```bash
planet subscriptions request \
    --name 'First Subscription' \
    --source request-catalog.json \
    --tools tools.json \
    --delivery cloud-delivery.json \
    | planet subscriptions create -
```

--------------------------------

### Create Features API Collection

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/async-sdk-guide

Demonstrates how to create a new collection within the Features API using the Python SDK. This involves initializing a FeaturesClient and calling the create_collection method.

```Python
async with Session() as sess:
  client = FeaturesClient(sess)
  new_collection = await client.create_collection(title="my collection", description="a new collection")
```

--------------------------------

### Authenticate with Environment Variable

Source: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/python/sdk-guide

Sets the Planet API key using the PL_API_KEY environment variable. This is the recommended method for authentication, allowing the SDK to access your credentials securely.

```bash
export PL_API_KEY=your_api_key
```
Tokens:
Raw