{"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":"python","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,"search_vec":"'0.9.0':42 'abil':30 'activ':45 'api':15,34 'asset':12 'build':17 'catalog':13,53 'client':2,4 'current':39 'develop':46 'endpoint':36 'function':27 'geospati':55 'higher':25 'higher-level':24 'imageri':51 'level':26 'leverag':32 'librari':21 'offer':23 'ongo':44 'packag':8 'pystac':1,3,20,50 'python':7 'raster':52 'regular':48 'releas':49 'seamless':37 'search':10,35 'spatiotempor':11 'stac':14,33,54 'upon':18 'version':40","created_at":"2026-04-15T18:44:26.229058+00:00","updated_at":"2026-04-16T19:52:56.178831+00:00","problems":[{"fix":"pip install pystac-client","cause":"The 'pystac-client' package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'pystac_client'"},{"fix":"from pystac import Asset, Item\nfrom pystac_client import Client","cause":"Core STAC objects like 'Asset', 'Item', and 'Collection' are part of the 'pystac' library, not 'pystac-client'.","error":"ImportError: cannot import name 'Asset' from 'pystac_client'"},{"fix":"search = client.search(datetime=\"2020-01-01T00:00:00Z/2020-01-02T23:59:59Z\")","cause":"The 'datetime' parameter provided to 'client.search()' does not conform to the strict ISO 8601 format required by the STAC API specification.","error":"ValueError: datetime must be a valid ISO 8601 datetime string or tuple of (start, end) strings."},{"fix":"client = Client.open(\"https://earth-search.aws.element84.com/v1\")\nsearch = client.search(\n    collections=[\"sentinel-2-l2a\"], # Ensure collection exists and is correctly spelled\n    datetime=\"2020-01-01T00:00:00Z/2020-01-01T23:59:59Z\", # Valid ISO 8601\n    bbox=[-105.78, 39.72, -105.77, 39.73], # Correct WGS84 order: min_lon, min_lat, max_lon, max_lat\n    limit=10\n)","cause":"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.","error":"requests.exceptions.HTTPError: 400 Client Error: Bad Request for url: ..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/stac-utils/pystac-client","docs":"https://pystac-client.readthedocs.io","changelog":"https://github.com/stac-utils/pystac-client/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/pystac-client/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}