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)[source]¶
Bases:
pystac.catalog.Catalog
A Client for interacting with the root of a STAC Catalog or API
Instances of the
Client
class inherit frompystac.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).- catalog_type¶
The catalog type. Defaults to
CatalogType.ABSOLUTE_PUBLISHED
.
- description¶
Detailed multi-line description to fully explain the catalog.
- extra_fields¶
Extra fields that are part of the top-level JSON properties of the Catalog.
- classmethod from_file(href, stac_io=None, headers={}, parameters=None)[source]¶
Open a STAC Catalog/API
- Returns
A Client (PySTAC Catalog) of the root Catalog for this Catalog/API
- Return type
- get_all_items()[source]¶
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)[source]¶
Get a single collection from this Catalog/API
- Parameters
collection_id – The Collection ID to get
- Returns
A STAC Collection
- Return type
- get_collections()[source]¶
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()[source]¶
Return all items of this catalog.
- Returns
Iterable[Item]:: Generator of items whose parent is this catalog.
- get_search_link()[source]¶
Returns this client’s search link.
Searches for a link with rel=”search” and either a GEOJSON or JSON media type.
- Returns
The search link, or None if there is not one found.
- Return type
Optional[pystac.Link]
- id¶
Identifier for the catalog.
- classmethod open(url, headers=None, parameters=None, ignore_conformance=False)[source]¶
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)[source]¶
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 theItemSearch
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 aNotImplementedError
.- 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"
.
- stac_extensions¶
List of extensions the Catalog implements.
- title¶
Optional short descriptive one-line title for the catalog.
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)[source]¶
- assets¶
Map of Assets
- description¶
Detailed multi-line description to fully explain the collection.
- extent¶
Spatial and temporal extents that describe the bounds of all items contained within this Collection.
- extra_fields¶
Extra fields that are part of the top-level JSON properties of the Collection.
- get_items()[source]¶
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]
- id¶
Identifier for the collection.
- keywords¶
Optional list of keywords describing the collection.
- providers¶
Optional list of providers of this Collection.
- stac_extensions¶
List of extensions the Collection implements.
- summaries¶
A map of property summaries, either a set of values or statistics such as a range.
- title¶
Optional short descriptive one-line title for the collection.
Item Search¶
The ItemSearch class represents 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, filter_lang=None, sortby=None, fields=None, max_items=None, method='POST', stac_io=None, client=None)[source]¶
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()
orItemSearch.items()
method is called and iterated over.
All “Parameters”, with the exception of
max_items
,method
, andurl
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"
, orNone
. IfNone
, this will default to"POST"
if theintersects
argument is present and"GET"
if not. If a"POST"
request receives a405
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 ofdatetime.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 ofNone
(['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 toYYYY-mm
or justYYYY
. Simple date strings will be expanded to include the entire time period, for example:2017
expands to2017-01-01T00:00:00Z/2017-12-31T23:59:59Z
2017-06
expands to2017-06-01T00:00:00Z/2017-06-30T23:59:59Z
2017-06-10
expands to2017-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 to2017-01-01T00:00:00Z/2018-12-31T23:59:59Z
2017-06/2017-07
expands to2017-06-01T00:00:00Z/2017-07-31T23:59:59Z
2017-06-10/2017-06-11
expands to2017-06-10T00:00:00Z/2017-06-11T23:59:59Z
intersects – A string or dictionary representing a GeoJSON geometry, or an object that implements a
__geo_interface__
property as supported by several libraries including Shapely, ArcPy, PySAL, and geojson. 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 searchedquery – 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
filter_lang – Language variant used in the filter body. If filter is a dictionary or not provided, defaults to ‘cql2-json’. If filter is a string, defaults to cql2-text.
sortby – A single field or list of fields to sort the response by
fields – A list of fields to include in the response. Note this may result in invalid STAC objects, as they may not have required fields. Use get_all_items_as_dict to avoid object unmarshalling 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 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()[source]¶
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()[source]¶
- 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()[source]¶
Iterator that yields ItemCollection objects. Each ItemCollection is a page of results from the search.
- Yields
Iterable[Item] – pystac_client.ItemCollection
- get_items()[source]¶
Iterator that yields
pystac.Item
instances for each item matching the given search parameters. CallsItemSearch.item_collections()
internally and yields fromItemCollection.features
for each page of results.- Returns
Iterate through resulting Items
- Return type
Iterable[Item]
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)[source]¶
Bases:
pystac.stac_io.DefaultStacIO
- assert_conforms_to(conformance_class)[source]¶
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)[source]¶
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
- get_pages(url, method='GET', parameters={})[source]¶
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)[source]¶
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 anyurllib.error.HTTPError
exceptions rather than catching them to allow us to handle different response status codes as needed.
- request(href, method='GET', headers={}, parameters={})[source]¶
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
- stac_object_from_dict(d, href=None, root=None, preserve_dict=True)[source]¶
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 parameterd
may be modified during this method call. Otherwise the dict is not mutated. Defaults toTrue
, which results results in a deepcopy of the parameter. Set toFalse
when possible to avoid the performance hit of a deepcopy.
Conformance¶
- class pystac_client.conformance.ConformanceClasses(value)[source]¶
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\\.'¶