PySTAC Client

Warnings

• deprecated The `get_all_items()` method on `ItemSearch` is deprecated. Users should migrate to `item_collection()` for retrieving all items as a single `ItemCollection` object.
  Fix: Replace `search.get_all_items()` with `search.item_collection()`.
• breaking The `STAC_URL` environment variable is no longer supported for automatically configuring the `Client.open()` method or the CLI. The STAC API URL must now be explicitly provided as an argument.
  Fix: Always pass the STAC API URL directly to `Client.open('your_stac_api_url')` or as a required positional argument in the CLI.
• gotcha When using `Client.collection_search()`, if the connected STAC API does not explicitly support the Collection Search Extension, `pystac-client` may perform client-side filtering. This can be inefficient for large catalogs and might not return comprehensive results from the server perspective.
  Fix: Check the STAC API's conformance (`client.conforms_to()`) for `CollectionSearch` to understand if server-side filtering is fully supported. Be mindful of potential performance implications for client-side filtering.
• gotcha Iterating through `search.items()` or `search.collections()` without setting `max_items` can lead to fetching and iterating over an entire large STAC catalog, potentially consuming significant memory and network resources.
  Fix: Always use `max_items` to limit results, or implement careful pagination/streaming logic if processing very large datasets is intended.
• gotcha The simplified query syntax (`query={property: value}`) often sends property values as strings (except for `gsd`). If the STAC API expects numeric or other data types for specific properties, this can lead to incorrect or no matches.
  Fix: For complex or type-sensitive queries, use the full JSON Query Extension syntax if the server supports it, or convert property values to the expected type on the server side if possible.
• gotcha Custom 'modifier' functions passed to `Client.open()` are expected to modify STAC objects in-place and return `None`. Returning a modified copy or a non-None value that isn't the original object can lead to unexpected behavior or warnings.
  Fix: Ensure custom modifier functions perform in-place modifications and explicitly return `None` (or implicitly by not having a `return` statement).

Install

• pip install pystac-client Install with pip

Imports

• Client

  from pystac_client import Client

Quickstart

This quickstart demonstrates how to connect to a STAC API, perform a basic item search using geographic bounding box and collection filters, and iterate through the results. It includes a placeholder for a STAC API URL, which can be overridden by an environment variable for easier testing.

import os
from pystac_client import Client

# Replace with a real STAC API URL or set via environment variable for testing
STAC_API_URL = os.environ.get('STAC_API_URL', 'https://earth-search.aws.element84.com/v1')

# 1. Create a client instance
client = Client.open(STAC_API_URL)
print(f"Connected to STAC API: {STAC_API_URL}")

# 2. Perform an item search
search = client.search(
    max_items=10,
    collections=['sentinel-2-l2a'],
    bbox=[-72.5, 40.5, -72, 41]
)

# 3. Get matched items and print IDs
matched_items_count = search.matched()
print(f"Found {matched_items_count} items.")

print("First 10 item IDs:")
for item in search.items():
    print(item.id)

# 4. Convert all items to an ItemCollection (use with caution for large results)
# item_collection = search.item_collection()
# print(f"ItemCollection contains {len(item_collection.items)} items.")