Registry / data / pystac-client

pystac-client

library0.9.0pypypi✓ verified 89d ago

PySTAC Client is a Python package for searching SpatioTemporal Asset Catalog (STAC) APIs. It builds upon the PySTAC library by offering higher-level functionality and the ability to leverage STAC API search endpoints seamlessly. The current version is 0.9.0, with ongoing active development and regular releases.

data http-networking

pip install pystac-client

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYSTAC-CLIENT

pystac-client

datapythonv0.9.0

Install

3.2s avg

Import

916ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.956s · 28MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.2s · import 0.876s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from pystac_client import Client

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.")

Debug

Known issues

deprecatedThe `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()`.

affects: 0.8.0+

breakingThe `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.

affects: Likely 0.8.x and above (removed around 0.2.0, fully phased out in later versions)

gotchaWhen 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.

affects: All versions

gotchaIterating 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.

affects: All versions

gotchaThe 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.

affects: All versions

gotchaCustom '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).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pystac_client'

The 'pystac-client' package has not been installed in the current Python environment.

fix

pip install pystac-client

ImportError: cannot import name 'Asset' from 'pystac_client'

Core STAC objects like 'Asset', 'Item', and 'Collection' are part of the 'pystac' library, not 'pystac-client'.

fix

from pystac import Asset, Item
from pystac_client import Client

ValueError: datetime must be a valid ISO 8601 datetime string or tuple of (start, end) strings.

The 'datetime' parameter provided to 'client.search()' does not conform to the strict ISO 8601 format required by the STAC API specification.

fix

search = client.search(datetime="2020-01-01T00:00:00Z/2020-01-02T23:59:59Z")

requests.exceptions.HTTPError: 400 Client Error: Bad Request for url: ...

The STAC API returned a 400 Bad Request error, typically indicating that the search parameters (e.g., collections, bbox, datetime) are invalid or malformed for the specific API endpoint.

fix

client = Client.open("https://earth-search.aws.element84.com/v1")
search = client.search(
    collections=["sentinel-2-l2a"], # Ensure collection exists and is correctly spelled
    datetime="2020-01-01T00:00:00Z/2020-01-01T23:59:59Z", # Valid ISO 8601
    bbox=[-105.78, 39.72, -105.77, 39.73], # Correct WGS84 order: min_lon, min_lat, max_lon, max_lat
    limit=10
)

Upgrade

Version history

0.9.0latest on PyPI · released Jul 18, 2025

Audit

Dependencies

pystacrequiredCore STAC object model.

python-dateutilrequiredDate/time parsing utilities.

requestsrequiredHTTP requests handling.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/stac-utils/pystac-client ↗

packagehttps://pypi.org/project/pystac-client/ ↗

docshttps://pystac-client.readthedocs.io ↗

changeloghttps://github.com/stac-utils/pystac-client/blob/main/CHANGELOG.md ↗