Planetary Computer SDK

1.0.0 · active · verified Thu Apr 16

The Planetary Computer SDK for Python (version 1.0.0) provides a client library for interacting with the Microsoft Planetary Computer, a platform that offers petabytes of Earth observation data and computational resources. It simplifies programmatic access to the SpatioTemporal Asset Catalog (STAC) API, handles data authentication by signing Azure Blob Storage URLs with Shared Access Signature (SAS) tokens, and facilitates integration with other open-source geospatial Python libraries. The project maintains an active development status with frequent updates for datasets and features, with new dataset releases typically on a roughly quarterly cadence.

Common errors

```
Failed to retrieve collections from ... The proxy tunnel request ... failed with status code '407'.
```
cause This error typically indicates an issue with network proxy configuration preventing the client from reaching the Planetary Computer API endpoints.

fix Ensure your network proxy settings are correctly configured for Python, or consult your IT department. You may need to set environment variables like `HTTP_PROXY` and `HTTPS_PROXY` or configure your Python environment to bypass the proxy for specific domains.
```
Read failed: The server failed to authenticate the request for ABFS.
```
cause This error most commonly occurs when trying to access an Azure Blob Storage URL (ABFS) without a valid or correctly applied Shared Access Signature (SAS) token, or if the token has expired.

fix Verify that `planetary_computer.sign_inplace` is being used correctly when opening the STAC client, or that `planetary_computer.sign()` is explicitly called on assets before accessing their `href`. Also, ensure your `PC_SDK_SUBSCRIPTION_KEY` (if used) is valid and provides sufficient access, and consider the token expiry mentioned in warnings.
```
APIError: The request exceeded the maximum allowed time, please try again.
```
cause This usually indicates a timeout on the Planetary Computer STAC API or Data API due to a complex query, a large number of results, or transient network issues.

fix Refine your STAC API queries to be more specific (e.g., tighter bounding box, shorter time range, more precise property filters). If processing large datasets, consider using Dask with `stackstac` to efficiently handle data and avoid pulling all assets into memory.
```
STAC validation errors during data ingestion (e.g., 'CollectionDoesNotExist', 'EmptyAsset', 'AssetTransformationError').
```
cause These errors occur when ingesting data into a Planetary Computer Pro GeoCatalog and are related to invalid STAC metadata, missing collections, or issues with the underlying asset files (e.g., corrupt GeoTIFFs, inaccessible URLs).

fix Thoroughly review the STAC JSON files for compliance with the STAC specification, ensure all referenced collections exist, and verify that all asset files are valid, accessible from the ingestion source, and in supported formats. Consult the Planetary Computer Pro ingestion troubleshooting documentation for specific error codes.

Warnings

gotcha Forgetting to sign asset URLs will result in 404 'Not Found' errors when attempting to access data from Azure Blob Storage. Data hosted on the Planetary Computer requires Shared Access Signature (SAS) tokens for authorized access.
Fix: Ensure you pass `modifier=planetary_computer.sign_inplace` when initializing `pystac_client.Client.open()` or manually call `planetary_computer.sign()` on individual assets/items before attempting to access their `href`s.
breaking In the May 2023 release, the underlying raster tiling engine (TiTiler) was upgraded, which introduced changes to how rendering parameters are specified when generating image tiles via the `/api/data/` endpoints (Item Tile and Mosaic Tile endpoints).
Fix: Review the changelog and upstream `pgstac-titiler` and `rio-tiler` documentation for updated rendering parameter specifications if you are directly interacting with the Planetary Computer's Data API tile endpoints.
deprecated The Planetary Computer Hub (a hosted Jupyter environment) was retired on June 6th, 2024, due to enhanced security requirements. This affects user workflows that relied on the pre-configured Hub environment.
Fix: Users should transition to local development environments or other Azure compute services (e.g., Azure Machine Learning compute instances, Azure Functions) to run their Python analyses. Data and APIs remain available.
gotcha Anonymous access to Planetary Computer data is rate-limited. For un-throttled access and longer-lived tokens, users should either register for a Planetary Computer API subscription key or perform their work within the West Europe Azure region.
Fix: Set the `PC_SDK_SUBSCRIPTION_KEY` environment variable with your API key or configure it via `planetarycomputer configure`. If possible, utilize Azure compute resources within the West Europe region.

Install

pip install planetary-computer pystac-client Install core libraries
pip install 'planetary-computer[io]' pystac-client stackstac rasterio xarray dask Install with common I/O and processing dependencies

Imports

planetary_computer
```
import planetary_computer
```
sign
```
from planetary_computer import sign
```
Used for manual signing of URLs or PySTAC objects.
sign_inplace
```
from planetary_computer import sign_inplace
```
Recommended for automatic signing of results from pystac-client.

Quickstart

This quickstart demonstrates how to connect to the Planetary Computer STAC API using `pystac-client`, perform a geospatial and temporal search for a Landsat image, and automatically sign the resulting asset URLs using `planetary_computer.sign_inplace`. It then shows how to open a signed Cloud Optimized GeoTIFF (COG) asset using `rasterio`. An optional environment variable `PC_SDK_SUBSCRIPTION_KEY` can be set for improved rate limits.

import os
import planetary_computer as pc
from pystac_client import Client
import rasterio

# Optionally set your Planetary Computer API subscription key for higher rate limits
# os.environ['PC_SDK_SUBSCRIPTION_KEY'] = os.environ.get('PC_SDK_SUBSCRIPTION_KEY', '')

# Open the Planetary Computer STAC API endpoint
# Using sign_inplace ensures all assets retrieved through this client are automatically signed
catalog = Client.open(
    "https://planetarycomputer.microsoft.com/api/stac/v1",
    modifier=pc.sign_inplace
)

# Define a bounding box and time range for a search (e.g., Landsat 8 image in Seattle area)
bbox = [-122.33, 47.60, -122.00, 47.75]
time_range = "2020-01-01/2020-01-31"

# Search for Landsat C2 L2 items
search = catalog.search(
    collections=["landsat-c2-l2"],
    bbox=bbox,
    datetime=time_range,
    query={'eo:cloud_cover': {'lt': 10}} # Example: filter for low cloud cover
)

# Get the first item from the search results
items = search.item_collection()
if items:
    first_item = items[0]
    print(f"Found item: {first_item.id}")

    # Access a signed asset (e.g., the red band)
    red_band_asset = first_item.assets["SR_B4"]
    signed_href = red_band_asset.href
    print(f"Signed URL for red band: {signed_href[:100]}...")

    # Open the signed asset with rasterio
    try:
        with rasterio.open(signed_href) as ds:
            print(f"Successfully opened asset with shape: {ds.shape}, CRS: {ds.crs}")
            # You can now read data, e.g., ds.read(1)
    except Exception as e:
        print(f"Error opening asset: {e}")
else:
    print("No items found for the given search criteria.")

view raw JSON →