Quickstart

pystac-client can be used as either a Command Line Interface (CLI) or a Python library.

CLI

Use the CLI to quickly make item- or collection-level searches and output or save the results.

The --matched switch performs a search with limit=1 so does not get any Items, but gets the total number of matches which will be output to the screen (if supported by the STAC API).

$ stac-client search https://earth-search.aws.element84.com/v1 -c sentinel-2-l2a --bbox -72.5 40.5 -72 41 --matched
3141 items matched

The --matched flag can also be used for collection search to get the total number of collections that match your search terms.

$ stac-client collections https://emc.spacebel.be --q sentinel-2 --matched
76 collections matched

If the same URL is to be used over and over, define an environment variable to be used in the CLI call:

$ export STAC_API_URL=https://earth-search.aws.element84.com/v1
$ stac-client search ${STAC_API_URL} -c sentinel-2-l2a --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --matched
48 items matched

Without the --matched switch, all items will be fetched, paginating if necessary. If the --max-items switch is provided it will stop paging once that many items has been retrieved. It then prints all items to stdout as an ItemCollection. This can be useful to pipe output to another process such as stac-terminal, geojsonio-cli, or jq.

$ stac-client search ${STAC_API_URL} -c sentinel-2-l2a --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 | stacterm cal --label platform

If the --save switch is provided instead, the results will not be output to stdout, but instead will be saved to the specified file.

$ stac-client search ${STAC_API_URL} -c sentinel-2-l2a --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --save items.json

If the Catalog supports the Query extension, any Item property can also be included in the search. Rather than requiring the JSON syntax the Query extension uses, pystac-client uses a simpler syntax that it will translate to the JSON equivalent. Note however that when the simple syntax is used it sends all property values to the server as strings, except for gsd which it casts to float. This means that if there are extensions in use with numeric properties these will be sent as strings. Some servers may automatically cast this to the appropriate data type, others may not.

The query filter will also accept complete JSON as per the specification.

<property><operator><value>

where operator is one of `>=`, `<=`, `>`, `<`, `=`

Examples:
eo:cloud_cover<10
created=2021-01-06
view:sun_elevation<20

Any number of properties can be included, and each can be included more than once to use additional operators.

$ stac-client search ${STAC_API_URL} -c sentinel-2-l2a --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 ---query "eo:cloud_cover<10" --matched
10 items matched

$ stac-client search ${STAC_API_URL} -c sentinel-2-l2a --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --query "eo:cloud_cover<10" "eo:cloud_cover>5" --matched
4 items matched

Collection searches can also use multiple filters like this example search for collections that include the term "biomass" and have a spatial extent that intersects Scandinavia.

$ stac-client collections https://emc.spacebel.be --q biomass --bbox 0.09 54.72 33.31 71.36  --matched
43 items matched

Since most STAC APIs have not yet implemented the collection search extension, pystac-client will perform a limited client-side filter on the full list of collections using only the bbox, datetime, and q (free-text search) parameters. In the case that the STAC API does not support collection search, a warning will be displayed to inform you that the filter is being applied client-side.

Python

To use the Python library, first a Client instance is created for a specific STAC API (use the root URL):

from pystac_client import Client

client = Client.open("https://earth-search.aws.element84.com/v1")

Create an item-level search:

search = client.search(
    max_items=10,
    collections=['sentinel-2-l2a'],
    bbox=[-72.5,40.5,-72,41]
)
print(f"{search.matched()} items found")

The items() iterator method can be used to iterate through all resulting items.

for item in search.items():
    print(item.id)

Use item_collection() to convert all Items from a search into a single PySTAC ItemCollection. The ItemCollection can then be saved as a GeoJSON FeatureCollection.

item_collection = search.item_collection()
item_collection.save_object('my_itemcollection.json')

Create a collection-level search:

collection_search = client.collection_search(
    q='"sentinel-2" OR "sentinel-1"',
)
print(f"{collection_search.matched()} collections found")

The collections() iterator method can be used to iterate through all resulting collections.

for collection in collection_search.collections():
    print(collection.id)