Usage

PySTAC-Client (pystac-client) builds upon PySTAC library to add support for STAC APIs in addition to static STAC catalogs. PySTAC-Client can be used with static or dynamic (i.e., API) catalogs. Currently, pystac-client does not offer much in the way of additional functionality if using with static catalogs, as the additional features are for support STAC API endpoints such as search. However, in the future it is expected that pystac-client will offer additional convenience functions that may be useful for static and dynamic catalogs alike.

The most basic implementation of a STAC API is an endpoint that returns a valid STAC Catalog, but also contains a "conformsTo" attribute that is a list of conformance URIs for the standards that the API supports.

This section is organized by the classes that are used, which mirror parent classes from PySTAC:

pystac-client	pystac
Client	Catalog
CollectionClient	Collection

The classes offer all of the same functions for accessing and traversing Catalogs as in PySTAC. The documentation for pystac-client only includes new functions, it does not duplicate documentation for inherited functions.

Client

The pystac_client.Client class is the main interface for working with services that conform to the STAC API spec. This class inherits from the pystac.Catalog class and in addition to the methods and attributes implemented by a Catalog, it also includes convenience methods and attributes for:

• Checking conformance to various specs

• Querying a search endpoint (if the API conforms to the STAC API - Item Search spec)

• Getting jsonschema of queryables from /queryables endpoint (if the API conforms to the STAC API - Filter spec)

The preferred way to interact with any STAC Catalog or API is to create an pystac_client.Client instance with the pystac_client.Client.open method on a root Catalog. This calls the pystac.STACObject.from_file() except it properly configures conformance and IO for reading from remote servers.

The following code creates an instance by making a call to the Microsoft Planetary Computer root catalog.

>>> from pystac_client import Client
>>> catalog = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1')
>>> catalog.title
'Microsoft Planetary Computer STAC API'

Some functions, such as Client.search will throw an error if the provided Catalog/API does not support the required Conformance Class. In other cases, such as Client.get_collections, API endpoints will be used if the API conforms, otherwise it will fall back to default behavior provided by pystac.Catalog.

When a Client does not conform to a particular Conformance Class, an informative warning is raised. Similarly when falling back to the pystac.Catalog implementation a warning is raised. You can control the behavior of these warnings using the standard warnings or special context managers pystac_client.warnings.strict() and from pystac_client.warnings.ignore().

API Conformance

This library is intended to work with any STAC static catalog or STAC API. A static catalog will be usable more or less the same as with PySTAC, except that pystac-client supports providing custom headers to API endpoints. (e.g., authenticating to an API with a token).

A STAC API is a STAC Catalog that is required to advertise its capabilities in a conformsTo field and implements the STAC API - Core spec along with other optional specifications:

• CORE

• ITEM_SEARCH

  • FIELDS

  • QUERY

  • SORT

  • CONTEXT

  • FILTER

• COLLECTIONS (based on the Features Collection section of OGC APO - Features <http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_>__)

• FEATURES (based on OGC API - Features)

The pystac_client.Client.conforms_to() method is used to check conformance against conformance classes (specs). To check an API for support for a given spec, pass the conforms_to function the name of a ConformanceClasses.

>>> catalog.conforms_to("ITEM_SEARCH")
True

If the API does not advertise conformance with a particular spec, but it does support it you can update conforms_to on the client object. For instance in v0 of earth-search there are no "conformsTo" uris set at all. But they can be explicitly set:

>>> catalog = Client.open("https://earth-search.aws.element84.com/v0")
<stdin>:1: NoConformsTo: Server does not advertise any conformance classes.
>>> catalog.conforms_to("ITEM_SEARCH")
False
>>> catalog.add_conforms_to("ITEM_SEARCH")

Note, updating "conformsTo" does not change what the server supports, it just changes PySTAC client’s understanding of what the server supports.

Configuring retry behavior

By default, pystac-client will retry requests that fail DNS lookup or have timeouts. If you’d like to configure this behavior, e.g. to retry on some 50x responses, you can configure the StacApiIO’s session:

from requests.adapters import HTTPAdapter
from urllib3 import Retry

from pystac_client import Client
from pystac_client.stac_api_io import StacApiIO

retry = Retry(
    total=5, backoff_factor=1, status_forcelist=[502, 503, 504], allowed_methods=None
)
stac_api_io = StacApiIO(max_retries=retry)
client = Client.open(
    "https://planetarycomputer.microsoft.com/api/stac/v1", stac_io=stac_api_io
)

Automatically modifying results

Some systems, like the Microsoft Planetary Computer, have public STAC metadata but require some authentication to access the actual assets.

pystac-client provides a modifier keyword that can automatically modify the STAC objects returned by the STAC API.

>>> from pystac_client import Client
>>> import planetary_computer, requests
>>> catalog = Client.open(
...    'https://planetarycomputer.microsoft.com/api/stac/v1',
...    modifier=planetary_computer.sign_inplace,
... )
>>> item = next(catalog.get_collection("sentinel-2-l2a").get_all_items())
>>> requests.head(item.assets["B02"].href).status_code
200

Without the modifier, we would have received a 404 error because the asset is in a private storage container.

pystac-client expects that the modifier callable modifies the result object in-place and returns no result. A warning is emitted if your modifier returns a non-None result that is not the same object as the input.

Here’s an example of creating your own modifier. Because Modifiable is a union, the modifier function must handle a few different types of input objects, and care must be taken to ensure that you are modifying the input object (rather than a copy). Simplifying this interface is a space for future improvement.

import urllib.parse

import pystac

from pystac_client import Client, Modifiable


def modifier(modifiable: Modifiable) -> None:
    if isinstance(modifiable, dict):
        if modifiable["type"] == "FeatureCollection":
            new_features = list()
            for item_dict in modifiable["features"]:
                modifier(item_dict)
                new_features.append(item_dict)
            modifiable["features"] = new_features
        else:
            stac_object = pystac.read_dict(modifiable)
            modifier(stac_object)
            modifiable.update(stac_object.to_dict())
    else:
        for key, asset in modifiable.assets.items():
            url = urllib.parse.urlparse(asset.href)
            if not url.query:
                asset.href = urllib.parse.urlunparse(url._replace(query="foo=bar"))
                modifiable.assets[key] = asset


client = Client.open(
    "https://planetarycomputer.microsoft.com/api/stac/v1", modifier=modifier
)
item_search = client.search(collections=["landsat-c2-l2"], max_items=1)
item = next(item_search.items())
asset = item.assets["red"]
assert urllib.parse.urlparse(asset.href).query == "foo=bar"

Using custom certificates

If you need to use custom certificates in your pystac-client requests, you can customize the StacApiIO instance before creating your Client.

>>> from pystac_client.stac_api_io import StacApiIO
>>> from pystac_client.client import Client
>>> stac_api_io = StacApiIO()
>>> stac_api_io.session.verify = "/path/to/certfile"
>>> client = Client.open("https://planetarycomputer.microsoft.com/api/stac/v1", stac_io=stac_api_io)

CollectionClient

STAC APIs may optionally implement a /collections endpoint as describe in the STAC API - Collections spec. This endpoint allows clients to search or inspect items within a particular collection.

>>> catalog = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1')
>>> collection = catalog.get_collection("sentinel-2-l2a")
>>> collection.title
'Sentinel-2 Level-2A'

pystac_client.CollectionClient overrides pystac.Collection.get_items(). PySTAC will get items by iterating through all children until it gets to an item link. PySTAC client will use the API endpoint instead: /collections/<collection_id>/items (as long as STAC API - Item Search spec is supported).

>>> item = next(collection.get_items(), None)

Note that calling list on this iterator will take a really long time since it will be retrieving every itme for the whole "sentinel-2-l2a" collection.

ItemSearch

STAC API services may optionally implement a /search endpoint as describe in the STAC API - Item Search spec. This endpoint allows clients to query STAC Items across the entire service using a variety of filter parameters. See the Query Parameter Table from that spec for details on the meaning of each parameter.

The pystac_client.Client.search() method provides an interface for making requests to a service’s “search” endpoint. This method returns a pystac_client.ItemSearch instance.

>>> from pystac_client import Client
>>> catalog = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1')
>>> results = catalog.search(
...     max_items=5
...     bbox=[-73.21, 43.99, -73.12, 44.05],
...     datetime=['2019-01-01T00:00:00Z', '2019-01-02T00:00:00Z'],
... )

Instances of ItemSearch have a handful of methods for getting matching items into Python objects. The right method to use depends on how many of the matches you want to consume (a single item at a time, a page at a time, or everything) and whether you want plain Python dictionaries representing the items, or proper pystac objects.

The following table shows the ItemSearch methods for fetching matches, according to which set of matches to return and whether to return them as pystac objects or plain dictionaries.

Matches to return	PySTAC objects	Plain dictionaries
Single items	items()	items_as_dicts()
Pages	pages()	pages_as_dicts()
Everything	item_collection()	item_collection_as_dict()

Additionally, the matched method can be used to access result metadata about how many total items matched the query:

• ItemSearch.matched: returns the number of hits (items) for this search if the API supports the STAC API Context Extension. Not all APIs support returning a total count, in which case a warning will be issued.

>>> for item in results.items():
...     print(item.id)
S2B_OPER_MSI_L2A_TL_SGS__20190101T200120_A009518_T18TXP_N02.11
MCD43A4.A2019010.h12v04.006.2019022234410
MCD43A4.A2019009.h12v04.006.2019022222645
MYD11A1.A2019002.h12v04.006.2019003174703
MYD11A1.A2019001.h12v04.006.2019002165238

The items() and related methods handle retrieval of successive pages of results by finding links with a "rel" type of "next" and parsing them to construct the next request. The default implementation of this "next" link parsing assumes that the link follows the spec for an extended STAC link as described in the STAC API - Item Search: Paging section. See the Paging docs for details on how to customize this behavior.

Alternatively, the Items can be returned within ItemCollections, where each ItemCollection is one page of results retrieved from search:

>>> for ic in results.pages():
...     for item in ic.items:
...         print(item.id)
S2B_OPER_MSI_L2A_TL_SGS__20190101T200120_A009518_T18TXP_N02.11
MCD43A4.A2019010.h12v04.006.2019022234410
MCD43A4.A2019009.h12v04.006.2019022222645
MYD11A1.A2019002.h12v04.006.2019003174703
MYD11A1.A2019001.h12v04.006.2019002165238

If you do not need the pystac.Item instances, you can instead use ItemSearch.items_as_dicts to retrieve dictionary representation of the items, without incurring the cost of creating the Item objects.

>>> for item_dict in results.items_as_dicts():
...     print(item_dict["id"])
S2B_OPER_MSI_L2A_TL_SGS__20190101T200120_A009518_T18TXP_N02.11
MCD43A4.A2019010.h12v04.006.2019022234410
MCD43A4.A2019009.h12v04.006.2019022222645
MYD11A1.A2019002.h12v04.006.2019003174703
MYD11A1.A2019001.h12v04.006.2019002165238

Query Extension

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 can use 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
view:off_nadir<50
platform=landsat-8

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

Sort Extension

If the Catalog supports the Sort extension, the search request can specify the order in which the results should be sorted with the sortby parameter. The sortby parameter can either be a string (e.g., "-properties.datetime,+id,collection"), a list of strings (e.g., ["-properties.datetime", "+id", "+collection"]), or a dictionary representing the POST JSON format of sortby. In the string and list formats, a - prefix means a descending sort and a + prefix or no prefix means an ascending sort.

>>> from pystac_client import Client
>>> results = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1').search(
...     sortby="properties.datetime"
... )
>>> results = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1').search(
...     sortby="-properties.datetime,+id,+collection"
... )
>>> results = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1').search(
...     sortby=["-properties.datetime", "+id" , "+collection" ]
... )
>>> results = Client.open('https://planetarycomputer.microsoft.com/api/stac/v1').search(
...     sortby=[
            {"direction": "desc", "field": "properties.datetime"},
            {"direction": "asc", "field": "id"},
            {"direction": "asc", "field": "collection"},
        ]
... )

Loading data

Once you’ve fetched your STAC Items with pystac-client, you now can work with the data referenced by your Assets. This is out of scope for pystac-client, but there’s a wide variety of tools and options available, and the correct choices depend on your type of data, your environment, and the type of analysis you’re doing.

For simple workflows, it can be easiest to load data directly using rasterio, fiona, and similar tools. Here is a simple example using rasterio to display data from a raster file.

>>> import rasterio.plot.show
>>> with rasterio.open(item.assets["data"].href) as dataset:
...     rasterio.plot.show(dataset)

For larger sets of data and more complex workflows, a common tool for working with a large number of raster files is xarray, which provides data structures for labelled multi-dimensional arrays. stackstac and odc-stac are two similar tools that can load asset data from Items or an ItemCollection into an xarray. Here’s a simple example from odc-stac’s documentation:

>>> catalog = pystac_client.Client.open(...)
>>> query = catalog.search(...)
>>> xx = odc.stac.load(
...     query.get_items(),
...     bands=["red", "green", "blue"],
...     resolution=100,
... )
>>> xx.red.plot.imshow(col="time")

See each packages’s respective documentation for more examples and tutorials.