API Reference

This section is autogenerated from in-line code documentation. It is mostly useful as a reference for the various classes, methods, and other objects in the library, but is not intended to function as a starting point for working with pystac_client.

Client

Client is the base PySTAC-Client that inherits from Catalog. In addition to the PySTAC functionality, Client allows opening of API URLs, understanding of conformance, and support for searching and paging through results.

class pystac_client.Client(id, description, title=None, stac_extensions=None, extra_fields=None, href=None, catalog_type=CatalogType.ABSOLUTE_PUBLISHED)

Bases: pystac.catalog.Catalog

A Client for interacting with the root of a STAC Catalog or API

Instances of the Client class inherit from pystac.Catalog and provide a convenient way of interacting with STAC Catalogs OR STAC APIs that conform to the STAC API spec. In addition to being a valid STAC Catalog APIs that have a "conformsTo" indicate that it supports additional functionality on top of a normal STAC Catalog, such as searching items (e.g., /search endpoint).

classmethod from_file(href, stac_io=None, headers={}, parameters=None)

Open a STAC Catalog/API

Returns

A Client (PySTAC Catalog) of the root Catalog for this Catalog/API

Return type

Client

get_all_items()

Get all items from this catalog and all subcatalogs. Will traverse any subcatalogs recursively, or use the /search endpoint if supported

Returns

Iterable[Item]:: All items that belong to this catalog, and all

catalogs or collections connected to this catalog through child links.

get_collection(collection_id)

Get a single collection from this Catalog/API

Parameters

collection_id – The Collection ID to get

Returns

A STAC Collection

Return type

CollectionClient

get_collections()

Get Collections in this Catalog

Gets the collections from the /collections endpoint if supported, otherwise fall back to Catalog behavior of following child links

Returns

Iterator through Collections in Catalog/API

Return type

Iterable[CollectionClient]

get_items()

Return all items of this catalog.

Returns

Iterable[Item]:: Generator of items whose parent is this catalog.

classmethod open(url, headers=None, parameters=None, ignore_conformance=False)

Opens a STAC Catalog or API This function will read the root catalog of a STAC Catalog or API

Parameters

• url – The URL of a STAC Catalog. If not specified, this will use the STAC_URL environment variable.

• headers – A dictionary of additional headers to use in all requests made to any part of this Catalog/API.

• ignore_conformance – Ignore any advertised Conformance Classes in this Catalog/API. This means that functions will skip checking conformance, and may throw an unknown error if that feature is not supported, rather than a NotImplementedError.

Returns

A Client instance for this Catalog/API

Return type

catalog

search(**kwargs)

Query the /search endpoint using the given parameters.

This method returns an ItemSearch instance, see that class’s documentation for details on how to get the number of matches and iterate over results. All keyword arguments are passed directly to the ItemSearch instance.

Warning

This method is only implemented if the API conforms to the STAC API - Item Search spec and contains a link with a "rel" type of "search" in its root catalog. If the API does not meet either of these criteria, this method will raise a NotImplementedError.

Parameters

**kwargs – Any parameter to the ItemSearch class, other than url, conformance, and stac_io which are set from this Client instance

Returns

An ItemSearch instance that can be used to iterate through Items.

Return type

search

Raises

NotImplementedError – If the API does not conform to the Item Search spec or does not have a link with a "rel" type of "search".

Collection Client

Client is the a PySTAC-Client that inherits from Collection. In addition to the PySTAC functionality, CollectionClient allows opening of API URLs, and iterating through items at a search endpoint, if supported.

class pystac_client.CollectionClient(id, description, extent, title=None, stac_extensions=None, href=None, extra_fields=None, catalog_type=None, license='proprietary', keywords=None, providers=None, summaries=None)

get_items()

Return all items in this Collection.

If the Collection contains a link of with a rel value of items, that link will be used to iterate through items. Otherwise, the default PySTAC behavior is assumed.

Returns

Generator of items whose parent is this catalog.

Return type

Iterable[Item]

Item Search

The ItemSearch class rerpesents a search of a STAC API.

class pystac_client.ItemSearch(url, *, limit=100, bbox=None, datetime=None, intersects=None, ids=None, collections=None, query=None, filter=None, sortby=None, fields=None, max_items=None, method='POST', stac_io=None, client=None)

Represents a deferred query to a STAC search endpoint as described in the STAC API - Item Search spec.

No request is sent to the API until a function is called to fetch or iterate through the resulting STAC Items,

either the ItemSearch.item_collections() or ItemSearch.items() method is called and iterated over.

All “Parameters”, with the exception of max_items, method, and url correspond to query parameters described in the STAC API - Item Search: Query Parameters Table docs. Please refer to those docs for details on how these parameters filter search results.

Parameters

• url – The URL to the item-search endpoint

• method – The HTTP method to use when making a request to the service. This must be either "GET", "POST", or None. If None, this will default to "POST" if the intersects argument is present and "GET" if not. If a "POST" request receives a 405 status for the response, it will automatically retry with a "GET" request for all subsequent requests.

• max_items – The maximum number of items to return from the search. Note that this is not a STAC API - Item Search parameter and is instead used by the client to limit the total number of returned items.

• limit – The maximum number of items to return per page. Defaults to None, which falls back to the limit set by the service.

• bbox – May be a list, tuple, or iterator representing a bounding box of 2D or 3D coordinates. Results will be filtered to only those intersecting the bounding box.

• datetime –

  Either a single datetime or datetime range used to filter results. You may express a single datetime using a datetime.datetime instance, a RFC 3339-compliant timestamp, or a simple date string (see below). Instances of datetime.datetime may be either timezone aware or unaware. Timezone aware instances will be converted to a UTC timestamp before being passed to the endpoint. Timezone unaware instances are assumed to represent UTC timestamps. You may represent a datetime range using a "/" separated string as described in the spec, or a list, tuple, or iterator of 2 timestamps or datetime instances. For open-ended ranges, use either ".." ('2020-01-01:00:00:00Z/..', ['2020-01-01:00:00:00Z', '..']) or a value of None (['2020-01-01:00:00:00Z', None]).

  If using a simple date string, the datetime can be specified in YYYY-mm-dd format, optionally truncating to YYYY-mm or just YYYY. Simple date strings will be expanded to include the entire time period, for example:

  • 2017 expands to 2017-01-01T00:00:00Z/2017-12-31T23:59:59Z

  • 2017-06 expands to 2017-06-01T00:00:00Z/2017-06-30T23:59:59Z

  • 2017-06-10 expands to 2017-06-10T00:00:00Z/2017-06-10T23:59:59Z

  If used in a range, the end of the range expands to the end of that day/month/year, for example:

  • 2017/2018 expands to 2017-01-01T00:00:00Z/2018-12-31T23:59:59Z

  • 2017-06/2017-07 expands to 2017-06-01T00:00:00Z/2017-07-31T23:59:59Z

  • 2017-06-10/2017-06-11 expands to 2017-06-10T00:00:00Z/2017-06-11T23:59:59Z

• intersects – A GeoJSON-like dictionary or JSON string. Results filtered to only those intersecting the geometry

• ids – List of Item ids to return. All other filter parameters that further restrict the number of search results (except limit) are ignored.

• collections – List of one or more Collection IDs or pystac.Collection instances. Only Items in one of the provided Collections will be searched

• query – List or JSON of query parameters as per the STAC API query extension

• filter – JSON of query parameters as per the STAC API filter extension

• sortby – A single field or list of fields to sort the response by

• fields – A list of fields to return in the response. Note this may result in invalid JSON. Use get_all_items_as_dict to avoid errors

• max_items – The maximum number of items to get, even if there are more matched items

• method – The http method, ‘GET’ or ‘POST’

• stac_io – An instance of of StacIO for retrieving results. Normally comes from the Client that returns this ItemSearch

• client – An instance of a root Client used to set the root on resulting Items

get_all_items()

Convenience method that builds an ItemCollection from all items matching the given search parameters.

Returns

ItemCollection

Return type

item_collection

get_all_items_as_dict()

Convenience method that gets all items from all pages, up to self._max_items,

and returns an array of dictionaries

Returns

A GeoJSON FeatureCollection

Return type

Dict

get_item_collections()

Iterator that yields ItemCollection objects. Each ItemCollection is a page of results from the search.

Yields

Iterable[Item] – pystac_client.ItemCollection

get_items()

Iterator that yields pystac.Item instances for each item matching the given search parameters. Calls ItemSearch.item_collections() internally and yields from ItemCollection.features for each page of results.

Returns

Iterate through resulting Items

Return type

Iterable[Item]

get_parameters()

matched()

Return number matched for search

Returns the value from the numberMatched or context.matched field. Not all APIs will support counts in which case a warning will be issued

Returns

Total count of matched items. If counts are not supported None is returned.

Return type

int

STAC API IO

The StacApiIO class inherits from the Collection class and allows for reading over http, such as with REST APIs.

class pystac_client.stac_api_io.StacApiIO(headers=None, conformance=None, parameters=None)

Bases: pystac.stac_io.DefaultStacIO

assert_conforms_to(conformance_class)

Raises a NotImplementedError if the API does not publish the given conformance class. This method only checks against the "conformsTo" property from the API landing page and does not make any additional calls to a /conformance endpoint even if the API provides such an endpoint.

Parameters

conformance_class – The ConformanceClasses key to check conformance against.

conforms_to(conformance_class)

Whether the API conforms to the given standard. This method only checks against the "conformsTo" property from the API landing page and does not make any additional calls to a /conformance endpoint even if the API provides such an endpoint.

Parameters

key – The ConformanceClasses key to check conformance against.

Returns

Indicates if the API conforms to the given spec or URI.

Return type

bool

get_pages(url, method='GET', parameters={})

Iterator that yields dictionaries for each page at a STAC paging endpoint, e.g., /collections, /search

Returns

JSON content from a single page

Return type

Dict

read_text(source, *args, parameters={}, **kwargs)

Read text from the given URI.

Overwrites the default method for reading text from a URL or file to allow urllib.request.Request instances as input. This method also raises any urllib.error.HTTPError exceptions rather than catching them to allow us to handle different response status codes as needed.

request(href, method='GET', headers={}, parameters={})

Makes a request to an http endpoint

Parameters

• href (str) – The request URL

• method (Optional[str], optional) – The http method to use, ‘GET’ or ‘POST’. Defaults to ‘GET’.

• headers (Optional[dict], optional) – Additional headers to include in request. Defaults to {}.

• parameters (Optional[dict], optional) – parameters to send with request. Defaults to {}.

Raises

APIError – raised if the server returns an error response

Returns

The decoded response from the endpoint

Return type

str

set_conformance(conformance)

Sets (or clears) the conformances for this StacIO.

stac_object_from_dict(d, href=None, root=None, preserve_dict=True)

Deserializes a STACObject sub-class instance from a dictionary.

Parameters

• d – The dictionary to deserialize

• href – Optional href to associate with the STAC object

• root – Optional root Catalog to associate with the STAC object.

• preserve_dict – If False, the dict parameter d may be modified during this method call. Otherwise the dict is not mutated. Defaults to True, which results results in a deepcopy of the parameter. Set to False when possible to avoid the performance hit of a deepcopy.

write_text_to_href(href, *args, **kwargs)

Writes text to file using UTF-8 encoding.

This implementation uses open() and therefore can only write to the local file system.

Parameters

• href – The path to which the file will be written.

• txt – The string content to write to the file.

Conformance

class pystac_client.conformance.ConformanceClasses(value)

Bases: enum.Enum

Enumeration class for Conformance Classes

COLLECTIONS = 'http://www\\.opengis\\.net/spec/ogcapi\\-features\\-1/1\\.0/conf/oas30'

CONTEXT = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/item\\-search\\#context'

CORE = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/core'

FIELDS = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/item\\-search\\#fields'

FILTER = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/item\\-search\\#filter'

ITEM_SEARCH = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/item\\-search'

QUERY = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/item\\-search\\#query'

SORT = 'https://api\\.stacspec\\.org/v1\\.0\\.(.*)/item\\-search\\#sort'

stac_prefix = 'https://api\\.stacspec\\.org/v1\\.0\\.'

Exceptions

exception pystac_client.exceptions.APIError

Bases: Exception

Raised when unexpected server error.

exception pystac_client.exceptions.ParametersError

Bases: Exception

Raised when invalid parameters are used in a query