Planet

https://docs.planet.com/
Admin
Planet is a cloud-native platform for Earth observation that provides reliable data, scalable...
Tokens:135,556
Snippets:973
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Set up environment with imports and helper function

Source: https://docs.planet.com/guides/subscribe-to-and-analyze-planetscope

Imports required libraries and defines a helper function to print formatted JSON. This setup is needed for the rest of the guide.

```python
from datetime import datetime, timezone, timedelta

from shapely.geometry import shape

from pprint import pprint

import geopandas as gpd

import pandas as pd

import requests

import numpy as np

import asyncio

import json

import copy

import os

import re



# Planet SDK

import planet

from planet.clients.subscriptions import SubscriptionsClient



from sentinelhub import (

    CRS,

    DataCollection,

    Geometry,

    SentinelHubStatistical,

    SentinelHubStatisticalDownloadClient,

    SHConfig,

    SentinelHubRequest,

    SentinelHubDownloadClient,

    MimeType,

)



from ipyleaflet import Map, GeoData, basemaps, LayersControl

import matplotlib.pyplot as plt

import matplotlib.dates as mdates

%matplotlib inline





# Helper function to printformatted JSON using the json module

def p(data):

    print(json.dumps(data, indent=2))
```

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

### Command-line invocation example

Source: https://docs.planet.com/data/planetary-variables/soil-water-content/techspec

Shows how to run the script with the example value 32770 and the expected output listing the active quality flags.

```bash
> python swc_quality_flags.py 32770

2. Low soil water content

16. Brightness temperature residuals too high (critical flag)
```

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

### S3-compatible delivery configuration in Python SDK

Source: https://docs.planet.com/develop/apis/subscriptions/delivery

Python SDK example using the s3_compatible function from planet.subscription_request. Reads credentials from environment variables and sets the same parameters as the JSON example.

```python
from os import getenv



from planet.subscription_request import s3_compatible



ACCESS_KEY_ID = getenv("ACCESS_KEY_ID")

SECRET_ACCESS_KEY = getenv("SECRET_ACCESS_KEY")



delivery = s3_compatible(

    endpoint="https://s3.foo.com",

    bucket="foo-bucket",

    region="foo-region",

    access_key_id=ACCESS_KEY_ID,

    secret_access_key=SECRET_ACCESS_KEY,

    use_path_style=False,

    path_prefix="folder1/prefix",

)
```

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

### Oracle Cloud Storage delivery Python SDK example

Source: https://docs.planet.com/develop/apis/subscriptions/delivery

Python SDK example using planet.subscription_request.oracle_cloud_storage. Reads credentials from environment variables ORACLE_ACCESS_ID and ORACLE_SECRET_KEY.

```Python
from os import getenv

from planet.subscription_request import oracle_cloud_storage

ORACLE_ACCESS_ID = getenv("ORACLE_ACCESS_ID")
ORACLE_SECRET_KEY = getenv("ORACLE_SECRET_KEY")

oracle_delivery = oracle_cloud_storage(
    customer_access_key_id=ORACLE_ACCESS_ID,
    customer_secret_key=ORACLE_SECRET_KEY,
    bucket="bucket-name",
    region="us-sanjose-1",
    namespace="ORACLE_NAMESPACE",
    path_prefix="folder1/prefix",
)
```

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

### Amazon S3 delivery Python SDK example

Source: https://docs.planet.com/develop/apis/subscriptions/delivery

Python SDK example using planet.subscription_request.amazon_s3 to create an S3 delivery object. Requires AWS credentials from environment variables.

```python
from os import getenv



from planet.subscription_request import amazon_s3



AWS_ACCESS_KEY_ID = getenv("AWS_ACCESS_KEY_ID")

AWS_SECRET_KEY = getenv("AWS_SECRET_KEY")



aws_delivery = amazon_s3(

    aws_access_key_id=AWS_ACCESS_KEY_ID,

    aws_secret_access_key=AWS_SECRET_KEY,

    aws_region="us-east-2",

    bucket="bucket-name",

    path_prefix="folder1/prefix",

)
```

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

### Subscription Source CLI Command

Source: https://docs.planet.com/develop/apis/subscriptions/sources

Example of requesting a subscription source using the Planet CLI.

```bash
planet subscriptions request-source \

    --source-id SWC-AMSR2-X_V5.0_1000 \

    --start-time 2022-12-07T00:00:00.0Z \

    --end-time 2022-12-16T00:00:00.0Z \

    --geometry pl:features/my/feature_collection-2q26z0q/mX9dB1o
```

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

### Subscription status output

Source: https://docs.planet.com/guides/analyze-historical-forest-carbon

Example output showing the subscription status as 'completed'.

```text
    completed
```

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

### DateRangeFilter example

Source: https://docs.planet.com/develop/apis/data/item-search

Example of a DateRangeFilter for searching items by a timestamp property (e.g., acquired). The config uses optional keys gte, gt, lt, or lte with RFC 3339 date values. This example returns items acquired after midnight on Dec 31, 2019 and on or before January 31, 2020.

```json
{

  "type": "DateRangeFilter",

  "field_name": "acquired",

  "config": {

    "gt": "2019-12-31T00:00:00Z",

    "lte": "2020-01-31T00:00:00Z"

  }

}
```

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

### Import libraries and set up authentication with keyring

Source: https://docs.planet.com/guides/analyze-historical-forest-carbon

Imports required Python packages and sets up authentication using keyring. Prompts for the Planet API key once and stores it securely in the system keyring. Set update to True to overwrite the stored key.

```python
# Import requirements

import base64

import keyring

import rasterio

import requests

import rioxarray as rx

import xarray as xr

import os

import pandas as pd

from io import StringIO



# Authentication

update = False # Set to True if you want to update the credentials in the system's keyring



if keyring.get_password("planet", "PL_API_KEY") is None or update:

    keyring.set_password("planet", "PL_API_KEY", "Your API Key")

else:

    print("Using stored api key")



PL_API_KEY = keyring.get_password("planet", "PL_API_KEY")
```

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

### Get subscription status

Source: https://docs.planet.com/guides/analyze-historical-forest-carbon

Sends a GET request to the subscription endpoint and returns the 'status' field. The status will be 'running' until the end date passes, then 'completed'.

```python
def get_subscription_status(subscription_id, auth):

    subscription_url = f"{BASE_URL}/{subscription_id}"

    response = requests.get(subscription_url, auth=auth)

    response_json = response.json()

    return response_json.get("status")



status = get_subscription_status(subscription_id, auth)

print(status)
```

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

### Quick Search with Sort (Python SDK)

Source: https://docs.planet.com/develop/apis/data/item-search

Python SDK example using the Planet client to perform a quick search with a date range filter and sorting by acquired time ascending. Returns an iterator of search results.

```python
from datetime import datetime

from planet import Planet, data_filter



pl = Planet()





def quick_search_with_sort() -> Iterator[dict]:

    filter = data_filter.date_range_filter(

        field_name="acquired",

        gte=datetime.fromisoformat("2022-04-14T00:00:00Z"),

        lte=datetime.fromisoformat("2022-04-15T00:00:00Z"),

    )



    return pl.data.search(

        ["PSScene"], search_filter=filter, sort="acquired asc", limit=10

    )
```

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

### NumberInFilter example

Source: https://docs.planet.com/develop/apis/data/item-search

Searches for items with a numerical property matching any of the given values. The config is an array of numbers. This example returns all items with a gsd value of 3.

```json
{

  "type": "NumberInFilter",

  "field_name": "gsd",

  "config": [3]

}
```

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

### Subscription Source Python SDK Configuration

Source: https://docs.planet.com/develop/apis/subscriptions/sources

Example of creating a subscription source using the Planet Python SDK with a Polygon geometry.

```python
from datetime import datetime



from planet.subscription_request import subscription_source





pv_source = subscription_source(

    source_id="SWC-AMSR2-X_V5.0_1000",

    start_time=datetime.fromisoformat("2022-12-07T00:00:00Z"),

    end_time=datetime.fromisoformat("2022-12-16T00:00:00Z"),

    geometry={

        "coordinates": [

            [

                [139.56481933, 35.42374884],

                [140.10314941, 35.42374884],

                [140.10314941, 35.77102915],

                [139.56481933, 35.77102915],

                [139.56481933, 35.42374884],

            ]

        ],

        "type": "Polygon",

    },

)
```

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

### Create PlanetScope subscriptions with Planet Python SDK

Source: https://docs.planet.com/guides/subscribe-to-and-analyze-planetscope

Sets up authentication with PL_API_KEY, defines start/end times and collection ID, then iterates over feature references to create subscriptions for PlanetScope 8-band imagery. Requires a feature collection reference and optionally a pre-existing collection ID; if None, a new collection is created. Output shows subscription IDs and the collection ID used for delivery.

```python
# Set up authentication

pl_api_key = os.getenv("PL_API_KEY")

auth = planet.Auth.from_key(pl_api_key)



# Set up variables for creating the subscriptions



# Define a start and end time

start_time = datetime(2024, 3, 1, tzinfo=timezone.utc)

end_time = datetime(2024, 11, 1, tzinfo=timezone.utc)



# Set a collection ID, or set it to None and the function will a create a new collection

collection_id = None # "insert-collection-id-for-pre-existing"



# List of subscriptions created

subscriptions = {}



async with planet.Session(auth=auth) as sess:



    cl = SubscriptionsClient(sess)



    #For each feature in our geojson feature collection

    for feature_ref in feature_refs:



        feature_collection_id = short_ref.split("/")[-2]

        feature_id = short_ref.split("/")[-1]



        # Create a name for the subscription

        subscription_name = f"{feature_collection_id}_{feature_id}_PlanetScope"



        # Build the subscription payload

        payload = planet.subscription_request.build_request(

            name=subscription_name,

            source=planet.subscription_request.catalog_source(

                start_time=start_time,

                end_time=end_time,

                item_types=["PSScene"],

                asset_types=["ortho_analytic_8b_sr", "ortho_analytic_8b_xml", "ortho_udm2"],

                geometry={

                    "type": "ref",

                    "content": feature_ref,

                },

            ),

            hosting=planet.subscription_request.sentinel_hub(collection_id=collection_id),

        )



        # Create the subscription

        results = await cl.create_subscription(payload)

        subscription_id = results["id"]

        subscriptions[feature_ref] = subscription_id

        print(f"Feature Reference: {feature_ref} -> Subscription ID: {subscription_id}")



        # If no collection ID is set, set the collection ID as the collection created for the first subscription that is created

        if not collection_id:

            results = await cl.get_subscription(subscription_id=subscriptions[0])

            collection_id = results["hosting"]["parameters"]["collection_id"]

            await asyncio.sleep(3) # delay so collection can be established



print(f"{len(subscriptions)} Subscriptions created. Data is being delivered to the following collection: {collection_id}")
```

```text
    Feature Reference: pl:features/my/agriculture-fields-JvVxVDr/1-0aLYrRg -> Subscription ID: 9242db6f-d325-4e4a-bfc2-be431025dd8d

    Feature Reference: pl:features/my/agriculture-fields-JvVxVDr/2-mEW2XBg -> Subscription ID: ef6c1d03-5965-4bfd-b4b4-4414f7dbe37b

    Feature Reference: pl:features/my/agriculture-fields-JvVxVDr/3-gBNDYVg -> Subscription ID: 9bc73504-d779-403e-b698-1fef8699c86b

    Feature Reference: pl:features/my/agriculture-fields-JvVxVDr/4-o4wld7m -> Subscription ID: 266d0642-14be-4c2b-9446-1900b79c6371

    4 Subscriptions created. Data is being delivered to the following collection: 65834003-ca52-41b9-b089-34a8fa4eb9c0
```

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

### Hosting with collection ID (JSON and Python SDK)

Source: https://docs.planet.com/develop/apis/subscriptions/delivery

Specifies the hosting block with a collection_id. The JSON example shows the request body, and the Python SDK example shows how to create a sentinel_hub delivery with a collection ID.

```json
"hosting": {

    "type": "sentinel_hub",

    "parameters": {

        "collection_id": "my_collection_id"

    }

}
```

```python
from planet.subscription_request import sentinel_hub



sh_delivery_collection = sentinel_hub(collection_id="my-collection-id")
```

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

### Catalog Source Python SDK

Source: https://docs.planet.com/develop/apis/subscriptions/sources

Python SDK example for creating a catalog source using the planet.subscription_request module.

```APIDOC
## Catalog Source Python SDK

### Description
Creates a catalog source using the Planet Python SDK's `catalog_source` function.

### Parameters
#### Function Parameters
- **item_types** (list of strings) - Required - List of item types, e.g., ["PSScene"].
- **asset_types** (list of strings) - Required - List of asset types, e.g., ["ortho_analytic_4b"].
- **start_time** (datetime) - Required - Start time of the subscription window.
- **end_time** (datetime) - Required - End time of the subscription window.
- **time_range_type** (string) - Required - Type of time range, e.g., "acquired".
- **geometry** (dict) - Required - GeoJSON geometry (Polygon) defining the area of interest.
- **geometry_relation** (string) - Required - Spatial relation, e.g., "intersects".

### Request Example
```python
from datetime import datetime
from planet.subscription_request import catalog_source

catalog_source = catalog_source(
    item_types=["PSScene"],
    asset_types=["ortho_analytic_4b"],
    start_time=datetime.fromisoformat("2024-11-05T00:00:00Z"),
    end_time=datetime.fromisoformat("2024-11-10T00:00:00Z"),
    time_range_type="acquired",
    geometry={
        "coordinates": [
            [
                [139.56481933, 35.42374884],
                [140.10314941, 35.42374884],
                [140.10314941, 35.77102915],
                [139.56481933, 35.77102915],
                [139.56481933, 35.42374884],
            ]
        ],
        "type": "Polygon",
    },
    geometry_relation="intersects",
)
```
```

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

### RangeFilter example

Source: https://docs.planet.com/develop/apis/data/item-search

Searches for items with a numerical property within a continuous range. The config supports optional keys gte, gt, lt, or lte. This example returns all items with cloud_cover less than or equal to 0.1 (10%).

```json
{

  "type": "RangeFilter",

  "field_name": "cloud_cover",

  "config": {

    "lte": 0.1

  }

}
```
Tokens:
Raw