{"id":6821,"library":"pystac-client","title":"PySTAC Client","description":"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.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/stac-utils/pystac-client","tags":["pystac","imagery","raster","catalog","STAC","geospatial"],"install":[{"cmd":"pip install pystac-client","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core STAC object model.","package":"pystac"},{"reason":"Date/time parsing utilities.","package":"python-dateutil"},{"reason":"HTTP requests handling.","package":"requests"}],"imports":[{"symbol":"Client","correct":"from pystac_client import Client"}],"quickstart":{"code":"import os\nfrom pystac_client import Client\n\n# Replace with a real STAC API URL or set via environment variable for testing\nSTAC_API_URL = os.environ.get('STAC_API_URL', 'https://earth-search.aws.element84.com/v1')\n\n# 1. Create a client instance\nclient = Client.open(STAC_API_URL)\nprint(f\"Connected to STAC API: {STAC_API_URL}\")\n\n# 2. Perform an item search\nsearch = client.search(\n    max_items=10,\n    collections=['sentinel-2-l2a'],\n    bbox=[-72.5, 40.5, -72, 41]\n)\n\n# 3. Get matched items and print IDs\nmatched_items_count = search.matched()\nprint(f\"Found {matched_items_count} items.\")\n\nprint(\"First 10 item IDs:\")\nfor item in search.items():\n    print(item.id)\n\n# 4. Convert all items to an ItemCollection (use with caution for large results)\n# item_collection = search.item_collection()\n# print(f\"ItemCollection contains {len(item_collection.items)} items.\")","lang":"python","description":"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."},"warnings":[{"fix":"Replace `search.get_all_items()` with `search.item_collection()`.","message":"The `get_all_items()` method on `ItemSearch` is deprecated. Users should migrate to `item_collection()` for retrieving all items as a single `ItemCollection` object.","severity":"deprecated","affected_versions":"0.8.0+"},{"fix":"Always pass the STAC API URL directly to `Client.open('your_stac_api_url')` or as a required positional argument in the CLI.","message":"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.","severity":"breaking","affected_versions":"Likely 0.8.x and above (removed around 0.2.0, fully phased out in later versions)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `max_items` to limit results, or implement careful pagination/streaming logic if processing very large datasets is intended.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure custom modifier functions perform in-place modifications and explicitly return `None` (or implicitly by not having a `return` statement).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}