API Reference

This API reference is auto-generated for the Python docstrings, and organized by the section of the STAC Spec they relate to, if related to a specific spec item.

pystac

PySTAC is a library for working with SpatioTemporal Asset Catalogs (STACs)

pystac.read_file(href)[source]

Reads a STAC object from a file.

This method will return either a Catalog, a Collection, or an Item based on what the file contains.

This is a convenience method for STACObject.from_file

Parameters:href (str) – The HREF to read the object from.
Returns:The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.
pystac.write_file(obj, include_self_link=True, dest_href=None)[source]

Writes a STACObject to a file.

This will write only the Catalog, Collection or Item obj. It will not attempt to write any other objects that are linked to obj; if you’d like functionality to save off catalogs recursively see Catalog.save.

This method will write the JSON of the object to the object’s assigned “self” link or to the dest_href if provided. To set the self link, see STACObject.set_self_href.

Convenience method for STACObject.from_file

Parameters:
  • obj (STACObject) – The STACObject to save.
  • include_self_link (bool) – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.
  • dest_href (str) – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.
pystac.read_dict(d, href=None, root=None)[source]

Reads a STAC object from a dict representing the serialized JSON version of the STAC object.

This method will return either a Catalog, a Collection, or an Item based on what the dict contains.

This is a convenience method for pystac.serialization.stac_object_from_dict()

Parameters:
  • d (dict) – The dict to parse.
  • href (str) – Optional href that is the file location of the object being parsed.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
pystac.set_stac_version(stac_version)[source]

Sets the STAC version that PySTAC should use.

This is the version that will be set as the “stac_version” property on any JSON STAC objects written by PySTAC. If set to None, the override version will be cleared if previously set and the default or an override taken from the environment will be used.

You can also set the environment variable PYSTAC_STAC_VERSION_OVERRIDE to override the version.

Parameters:stac_version (str) – The STAC version to use instead of the latest STAC version that PySTAC supports (described in STACVersion.DEFAULT_STAC_VERSION)

Note

Setting the STAC version to something besides the default version will not effect the format of STAC read or written; it will only override the stac_version property of the objects being written. Setting this incorrectly can produce invalid STAC.

pystac.get_stac_version()[source]

Returns the STAC version PySTAC writes as the “stac_version” property for any object it serializes into JSON.

If a call to set_stac_version was made, this will return the value it was called with. Next it will check the environment for a PYSTAC_STAC_VERSION_OVERRIDE variable. Otherwise it will return the latest STAC version that this version of PySTAC supports.

Returns:The STAC Version PySTAC is set up to use.
Return type:str

STACObject

STACObject is the base class for Catalog, Collection and Item, and contains a variety of useful methods for dealing with links, copying objects, accessing extensions, and reading and writing files. You shouldn’t use STACObject directly, but instead access this functionality through the implementing classes.

class pystac.STACObject(stac_extensions)[source]

A STACObject is the base class for any element of STAC that has links e.g. (Catalogs, Collections, or Items). A STACObject has common functionality, can be converted to and from Python dicts representing JSON, and can be cloned or copied.

A list of Link objects representing all links associated with this STACObject.

Type:List[Link]
STAC_OBJECT_TYPE = None

Add a link to this object’s set of links.

Parameters:link (Link) – The link to add.

Add links to this object’s set of links.

Parameters:links (List[Link]) – The links to add.

Clears all Link instances associated with this object.

Parameters:rel (str or None) – If set, only clear links that match this relationship.
clone()[source]

Clones this object.

Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use STACObject.full_copy.

Returns:The clone of this object.
Return type:STACObject
ext

Access extensions for this STACObject.

Example

This example shows accessing a Item’s EO extension functionality that gets the band information for an asset:

item = pystac.read_file("eo_item.json")
bands = item.ext.eo.get_asset_bands(item.assets["image"])
Returns:The object that can be used to access extension information and functionality.
Return type:ExtensionIndex
classmethod from_dict(d, href=None, root=None)[source]

Parses this STACObject from the passed in dictionary.

Parameters:
  • d (dict) – The dict to parse.
  • href (str) – Optional href that is the file location of the object being parsed.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns:

The STACObject parsed from this dict.

Return type:

STACObject

classmethod from_file(href)[source]

Reads a STACObject implementation from a file.

Parameters:href (str) – The HREF to read the object from.
Returns:The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.
full_copy(root=None, parent=None)[source]

Create a full copy of this STAC object and any stac objects linked to by this object.

Parameters:
  • root (STACObject) – Optional root to set as the root of the copied object, and any other copies that are contained by this object.
  • parent (STACObject) – Optional parent to set as the parent of the copy of this object.
Returns:

A full copy of this object, as well as any objects this object

links to.

Return type:

STACObject

Gets the Link instances associated with this object.

Parameters:rel (str or None) – If set, filter links such that only those matching this relationship are returned.
Returns:
A list of links that match rel if set,
or else all links associated with this object.
Return type:List[Link]
get_parent()[source]

Get the Catalog or Collection to the parent for this object. The root is represented by a Link with rel == 'parent'.

Returns:The parent object for this object, or None if no root link is set.
Return type:Catalog, Collection, or None
get_root()[source]

Get the Catalog or Collection to the root for this object. The root is represented by a Link with rel == 'root'.

Returns:The root object for this object, or None if no root link is set.
Return type:Catalog, Collection, or None

Get the Link representing the root for this object.

Returns:The root link for this object, or None if no root link is set.
Return type:Link or None
get_self_href()

Gets the absolute HREF that is represented by the rel == 'self' Link.

Returns:The absolute HREF of this object, or None if there is no self link defined.
Return type:str or None

Note

A self link can exist for objects, even if the link is not read or written to the JSON-serialized version of the object. Any object read from STACObject.from_file will have the HREF the file was read from set as it’s self HREF. All self links have absolute (as opposed to relative) HREFs.

Get single link that match the given rel.

Parameters:rel (str) – The Link rel to match on.
get_stac_objects(rel)[source]

Gets the STACObject instances that are linked to by links with their rel property matching the passed in argument.

Parameters:rel (str) – The relation to match each Link’s rel property against.
Returns:A possibly empty generator of STACObjects that are connected to this object through links with the given rel.
Return type:Generator[STACObjects]

Remove links to this object’s set of links that match the given rel.

Parameters:rel (str) – The Link rel to match on.

Ensure all STACObjects linked to by this STACObject are resolved. This is important for operations such as changing HREFs.

This method mutates the entire catalog tree.

save_object(include_self_link=True, dest_href=None)[source]

Saves this STAC Object to it’s ‘self’ HREF.

Parameters:
  • include_self_link (bool) – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.
  • dest_href (str) – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.
Raises:

STACError – If no self href is set, this error will be raised.

Note

When to include a self link is described in the Use of Links section of the STAC best practices document

set_parent(parent)[source]

Sets the parent Catalog or Collection for this object.

Parameters:parent (Catalog, Collection or None) – The parent object to set. Passing in None will clear the parent.
set_root(root)[source]

Sets the root Catalog or Collection for this object.

Parameters:root (Catalog, Collection or None) – The root object to set. Passing in None will clear the root.
set_self_href(href)

Sets the absolute HREF that is represented by the rel == 'self' Link.

Parameters:href (str) – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.
to_dict(include_self_link=True)[source]

Generate a dictionary representing the JSON of this serialized object.

Parameters:include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted.
Returns:A serializion of the object that can be written out as JSON.
Return type:dict
validate()[source]

Validate this STACObject.

Raises:STACValidationError
class pystac.STACObjectType[source]

An enumeration.

CATALOG = 'CATALOG'
COLLECTION = 'COLLECTION'
ITEM = 'ITEM'
ITEMCOLLECTION = 'ITEMCOLLECTION'

Catalog Spec

These classes are representations of the Catalog Spec.

Catalog

class pystac.Catalog(id, description, title=None, stac_extensions=None, extra_fields=None, href=None, catalog_type=<CatalogType.ABSOLUTE_PUBLISHED: 'ABSOLUTE_PUBLISHED'>)[source]

Bases: pystac.stac_object.STACObject

A PySTAC Catalog represents a STAC catalog in memory.

A Catalog is a STACObject that may contain children, which are instances of Catalog or Collection, as well as Item s.

Parameters:
  • id (str) – Identifier for the catalog. Must be unique within the STAC.
  • description (str) – Detailed multi-line description to fully explain the catalog. CommonMark 0.28 syntax MAY be used for rich text representation.
  • title (str or None) – Optional short descriptive one-line title for the catalog.
  • stac_extensions (List[str]) – Optional list of extensions the Catalog implements.
  • href (str or None) – Optional HREF for this catalog, which be set as the catalog’s self link’s HREF.
  • catalog_type (str or None) – Optional catalog type for this catalog. Must be one of the values in :class`~pystac.CatalogType`.
id

Identifier for the catalog.

Type:str
description

Detailed multi-line description to fully explain the catalog.

Type:str
title

Optional short descriptive one-line title for the catalog.

Type:str or None
stac_extensions

Optional list of extensions the Catalog implements.

Type:List[str] or None
extra_fields

Extra fields that are part of the top-level JSON properties of the Catalog.

Type:dict or None

A list of Link objects representing all links associated with this Catalog.

Type:List[Link]
catalog_type

The catalog type, or None if not known.

Type:str or None
DEFAULT_FILE_NAME = 'catalog.json'

Default file name that will be given to this STAC object in a cononical format.

STAC_OBJECT_TYPE = 'CATALOG'
add_child(child, title=None, strategy=None)[source]

Adds a link to a child Catalog or Collection. This method will set the child’s parent to this object, and its root to this Catalog’s root.

Parameters:
add_children(children)[source]

Adds links to multiple Catalog or `~pystac.Collection`s. This method will set each child’s parent to this object, and their root to this Catalog’s root.

Parameters:children (Iterable[Catalog or Collection]) – The children to add.
add_item(item, title=None, strategy=None)[source]

Adds a link to an Item. This method will set the item’s parent to this object, and its root to this Catalog’s root.

Parameters:
  • item (Item) – The item to add.
  • title (str) – Optional title to give to the Link
add_items(items)[source]

Adds links to multiple Item s. This method will set each item’s parent to this object, and their root to this Catalog’s root.

Parameters:items (Iterable[Item]) – The items to add.
clear_children()[source]

Removes all children from this catalog.

Returns:Returns self
Return type:Catalog
clear_items()[source]

Removes all items from this catalog.

Returns:Returns self
Return type:Catalog
clone()[source]

Clones this object.

Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use STACObject.full_copy.

Returns:The clone of this object.
Return type:STACObject
describe(include_hrefs=False, _indent=0)[source]

Prints out information about this Catalog and all contained STACObjects.

Parameters:include_hrefs (bool) – HREF along with the object ID.
classmethod from_dict(d, href=None, root=None)[source]

Parses this STACObject from the passed in dictionary.

Parameters:
  • d (dict) – The dict to parse.
  • href (str) – Optional href that is the file location of the object being parsed.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns:

The STACObject parsed from this dict.

Return type:

STACObject

generate_subcatalogs(template, defaults=None, parent_ids=None, **kwargs)[source]

Walks through the catalog and generates subcatalogs for items based on the template string. See LayoutTemplate for details on the construction of template strings. This template string will be applied to the items, and subcatalogs will be created that separate and organize the items based on template values.

Parameters:
  • template (str) – A template string that can be consumed by a LayoutTemplate
  • defaults (dict) – Default values for the template variables that will be used if the property cannot be found on the item.
  • parent_ids (List[str]) – Optional list of the parent catalogs’ identifiers. If the bottom-most subcatalags already match the template, no subcatalog is added.
Returns:

List of new catalogs created

Return type:

[catalog]

get_all_items()[source]

Get all items from this catalog and all subcatalogs. Will traverse any subcatalogs recursively.

Returns:
All items that belong to this catalog, and all
catalogs or collections connected to this catalog through child links.
Return type:Generator[Item]
get_child(id, recursive=False)[source]

Gets the child of this catalog with the given ID, if it exists.

Parameters:
  • id (str) – The ID of the child to find.
  • recursive (bool) – If True, search this catalog and all children for the item; otherwise, only search the children of this catalog. Defaults to False.
Returns:

The item with the given ID, or None if not found.

Return type:

Item or None

Return all child links of this catalog.

Returns:List of links of this catalog with rel == 'child'
Return type:List[Link]
get_children()[source]

Return all children of this catalog.

Returns:Generator of children who’s parent is this catalog.
Return type:Generator[Catalog or Collection]
get_item(id, recursive=False)[source]

Returns an item with a given ID.

Parameters:
  • id (str) – The ID of the item to find.
  • recursive (bool) – If True, search this catalog and all children for the item; otherwise, only search the items of this catalog. Defaults to False.
Returns:

The item with the given ID, or None if not found.

Return type:

Item or None

Return all item links of this catalog.

Returns:List of links of this catalog with rel == 'item'
Return type:List[Link]
get_items()[source]

Return all items of this catalog.

Returns:Generator of items who’s parent is this catalog.
Return type:Generator[Item]
is_relative()[source]
make_all_asset_hrefs_absolute()[source]

Makes all the HREFs of assets belonging to items in this catalog and all children to be absolute, recursively.

make_all_asset_hrefs_relative()[source]

Makes all the HREFs of assets belonging to items in this catalog and all children to be relative, recursively.

map_assets(asset_mapper)[source]

Creates a copy of a catalog, with each Asset for each Item passed through the asset_mapper function.

Parameters:asset_mapper (Callable) – A function that takes in an key and an Asset, and returns either an Asset, a (key, Asset), or a dictionary of Assets with unique keys. The Asset that is passed into the item_mapper is a copy, so the method can mutate it safely.
Returns:A full copy of this catalog, with assets manipulated according to the asset_mapper function.
Return type:Catalog
map_items(item_mapper)[source]

Creates a copy of a catalog, with each item passed through the item_mapper function.

Parameters:item_mapper (Callable) – A function that takes in an item, and returns either an item or list of items. The item that is passed into the item_mapper is a copy, so the method can mutate it safely.
Returns:A full copy of this catalog, with items manipulated according to the item_mapper function.
Return type:Catalog
normalize_and_save(root_href, catalog_type=None, strategy=None)[source]

Normalizes link HREFs to the given root_href, and saves the catalog.

This is a convenience method that simply calls Catalog.normalize_hrefs and Catalog.save in sequence.

Parameters:
  • root_href (str) – The absolute HREF that all links will be normalized against.
  • catalog_type (str) – The catalog type that dictates the structure of the catalog to save. Use a member of CatalogType. Defaults to the root catalog.catalog_type or the current catalog catalog_type if there is no root catalog.
  • strategy (HrefLayoutStrategy) – The layout strategy to use in setting the HREFS for this catalog. Defaults to BestPracticesLayoutStrategy
normalize_hrefs(root_href, strategy=None)[source]

Normalize HREFs will regenerate all link HREFs based on an absolute root_href and the canonical catalog layout as specified in the STAC specification’s best practices.

This method mutates the entire catalog tree.

Parameters:
  • root_href (str) – The absolute HREF that all links will be normalized against.
  • strategy (HrefLayoutStrategy) – The layout strategy to use in setting the HREFS for this catalog. Defaults to BestPracticesLayoutStrategy
See:
STAC best practices document for the canonical layout of a STAC.
remove_child(child_id)[source]

Removes an child from this catalog.

Parameters:child_id (str) – The ID of the child to remove.
remove_item(item_id)[source]

Removes an item from this catalog.

Parameters:item_id (str) – The ID of the item to remove.
save(catalog_type=None)[source]

Save this catalog and all it’s children/item to files determined by the object’s self link HREF.

Parameters:catalog_type (str) – The catalog type that dictates the structure of the catalog to save. Use a member of CatalogType. If not supplied, the catalog_type of this catalog will be used. If that attribute is not set, an exception will be raised.

Note

If the catalog type is CatalogType.ABSOLUTE_PUBLISHED, all self links will be included, and hierarchical links be absolute URLs. If the catalog type is CatalogType.RELATIVE_PUBLISHED, this catalog’s self link will be included, but no child catalog will have self links, and hierarchical links will be relative URLs If the catalog type is CatalogType.SELF_CONTAINED, no self links will be included and hierarchical links will be relative URLs.

set_root(root)[source]

Sets the root Catalog or Collection for this object.

Parameters:root (Catalog, Collection or None) – The root object to set. Passing in None will clear the root.
to_dict(include_self_link=True)[source]

Generate a dictionary representing the JSON of this serialized object.

Parameters:include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted.
Returns:A serializion of the object that can be written out as JSON.
Return type:dict
validate_all()[source]

Validates each catalog, collection contained within this catalog.

Walks through the children and items of the catalog and validates each stac object.

Raises:STACValidationError – Raises this error on any item that is invalid. Will raise on the first invalid stac object encountered.
walk()[source]

Walks through children and items of catalogs.

For each catalog in the STAC’s tree rooted at this catalog (including this catalog itself), it yields a 3-tuple (root, subcatalogs, items). The root in that 3-tuple refers to the current catalog being walked, the subcatalogs are any catalogs or collections for which the root is a parent, and items represents any items that have the root as a parent.

This has similar functionality to Python’s os.walk().

Returns:A generator that yields a 3-tuple (parent_catalog, children, items).
Return type:Generator[(Catalog, Generator[Catalog], Generator[Item])]

CatalogType

class pystac.CatalogType[source]

An enumeration.

ABSOLUTE_PUBLISHED = 'ABSOLUTE_PUBLISHED'

Absolute Published Catalog is a catalog that uses absolute links for everything, both in the links objects and in the asset hrefs.

See:
The best practices documentation on published catalogs
RELATIVE_PUBLISHED = 'RELATIVE_PUBLISHED'

Relative Published Catalog is a catalog that uses relative links for everything, but includes an absolute self link at the root catalog, to identify its online location.

See:
The best practices documentation on published catalogs
SELF_CONTAINED = 'SELF_CONTAINED'

A ‘self-contained catalog’ is one that is designed for portability. Users may want to download a catalog from online and be able to use it on their local computer, so all links need to be relative.

See:
The best practices documentation on self-contained catalogs

Collection Spec

These classes are representations of the Collection Spec.

Collection

class pystac.Collection(id, description, extent, title=None, stac_extensions=None, href=None, extra_fields=None, catalog_type=None, license='proprietary', keywords=None, providers=None, properties=None, summaries=None)[source]

Bases: pystac.catalog.Catalog

A Collection extends the Catalog spec with additional metadata that helps enable discovery.

Parameters:
  • id (str) – Identifier for the collection. Must be unique within the STAC.
  • description (str) –

    Detailed multi-line description to fully explain the collection. CommonMark 0.28 syntax MAY be used for rich text representation.

  • extent (Extent) – Spatial and temporal extents that describe the bounds of all items contained within this Collection.
  • title (str or None) – Optional short descriptive one-line title for the collection.
  • stac_extensions (List[str]) – Optional list of extensions the Collection implements.
  • href (str or None) – Optional HREF for this collection, which be set as the collection’s self link’s HREF.
  • catalog_type (str or None) – Optional catalog type for this catalog. Must be one of the values in :class`~pystac.CatalogType`.
  • license (str) – Collection’s license(s) as a SPDX License identifier, various, or proprietary. If collection includes data with multiple different licenses, use various and add a link for each. Defaults to ‘proprietary’.
  • keywords (List[str]) – Optional list of keywords describing the collection.
  • providers (List[Provider]) – Optional list of providers of this Collection.
  • properties (dict) – Optional dict of common fields across referenced items.
  • summaries (dict) – An optional map of property summaries, either a set of values or statistics such as a range.
  • extra_fields (dict or None) – Extra fields that are part of the top-level JSON properties of the Collection.
id

Identifier for the collection.

Type:str
description

Detailed multi-line description to fully explain the collection.

Type:str
extent

Spatial and temporal extents that describe the bounds of all items contained within this Collection.

Type:Extent
title

Optional short descriptive one-line title for the collection.

Type:str or None
stac_extensions

Optional list of extensions the Collection implements.

Type:List[str]
keywords

Optional list of keywords describing the collection.

Type:List[str] or None
providers

Optional list of providers of this Collection.

Type:List[Provider] or None
properties

Optional dict of common fields across referenced items.

Type:dict or None
summaries

An optional map of property summaries, either a set of values or statistics such as a range.

Type:dict or None

A list of Link objects representing all links associated with this Collection.

Type:List[Link]
extra_fields

Extra fields that are part of the top-level JSON properties of the Catalog.

Type:dict or None
DEFAULT_FILE_NAME = 'collection.json'

Default file name that will be given to this STAC object in a cononical format.

STAC_OBJECT_TYPE = 'COLLECTION'
add_item(item, title=None)[source]

Adds a link to an Item. This method will set the item’s parent to this object, and its root to this Catalog’s root.

Parameters:
  • item (Item) – The item to add.
  • title (str) – Optional title to give to the Link
clone()[source]

Clones this object.

Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use STACObject.full_copy.

Returns:The clone of this object.
Return type:STACObject
classmethod from_dict(d, href=None, root=None)[source]

Parses this STACObject from the passed in dictionary.

Parameters:
  • d (dict) – The dict to parse.
  • href (str) – Optional href that is the file location of the object being parsed.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns:

The STACObject parsed from this dict.

Return type:

STACObject

to_dict(include_self_link=True)[source]

Generate a dictionary representing the JSON of this serialized object.

Parameters:include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted.
Returns:A serializion of the object that can be written out as JSON.
Return type:dict
update_extent_from_items()[source]

Update datetime and bbox based on all items to a single bbox and time window.

Extent

class pystac.Extent(spatial, temporal)[source]

Describes the spatio-temporal extents of a Collection.

Parameters:
  • spatial (SpatialExtent) – Potential spatial extent covered by the collection.
  • temporal (TemporalExtent) – Potential temporal extent covered by the collection.
spatial

Potential spatial extent covered by the collection.

Type:SpatialExtent
temporal

Potential temporal extent covered by the collection.

Type:TemporalExtent
clone()[source]

Clones this object.

Returns:The clone of this extent.
Return type:Extent
static from_dict(d)[source]

Constructs an Extent from a dict.

Returns:The Extent deserialized from the JSON dict.
Return type:Extent
static from_items(items)[source]

Create an Extent based on the datetimes and bboxes of a list of items.

Parameters:items (List[Item]) – A list of items to derive the extent from.
Returns:
An Extent that spatially and temporally covers all of the
given items.
Return type:Extent
to_dict()[source]

Generate a dictionary representing the JSON of this Extent.

Returns:A serializion of the Extent that can be written out as JSON.
Return type:dict

SpatialExtent

class pystac.SpatialExtent(bboxes)[source]

Describes the spatial extent of a Collection.

Parameters:bboxes (List[List[float]]) – A list of bboxes that represent the spatial extent of the collection. Each bbox can be 2D or 3D. The length of the bbox array must be 2*n where n is the number of dimensions. For example, a 2D Collection with only one bbox would be [[xmin, ymin, xmax, ymax]]
bboxes

A list of bboxes that represent the spatial extent of the collection. Each bbox can be 2D or 3D. The length of the bbox array must be 2*n where n is the number of dimensions. For example, a 2D Collection with only one bbox would be [[xmin, ymin, xmax, ymax]]

Type:List[List[float]]
clone()[source]

Clones this object.

Returns:The clone of this object.
Return type:SpatialExtent
static from_coordinates(coordinates)[source]

Constructs a SpatialExtent from a set of coordinates.

This method will only produce a single bbox that covers all points in the coordinate set.

Parameters:coordinates (List[float]) – Coordinates to derive the bbox from.
Returns:A SpatialExtent with a single bbox that covers the given coordinates.
Return type:SpatialExtent
static from_dict(d)[source]

Constructs an SpatialExtent from a dict.

Returns:The SpatialExtent deserialized from the JSON dict.
Return type:SpatialExtent
to_dict()[source]

Generate a dictionary representing the JSON of this SpatialExtent.

Returns:A serializion of the SpatialExtent that can be written out as JSON.
Return type:dict

TemporalExtent

class pystac.TemporalExtent(intervals)[source]

Describes the temporal extent of a Collection.

Parameters:
  • intervals (List[List[datetime]]) – A list of two datetimes wrapped in a list,
  • the temporal extent of a Collection. Open date ranges are supported (representing) –
  • setting either the start (by) –
  • element of the interval) to None. (second) –
intervals

A list of two datetimes wrapped in a list,

Type:List[List[datetime]]
representing the temporal extent of a Collection. Open date ranges are represented
by either the start
Type:the first element of the interval
second element of the interval) being None.

Note

Datetimes are required to be in UTC.

clone()[source]

Clones this object.

Returns:The clone of this object.
Return type:TemporalExtent
static from_dict(d)[source]

Constructs an TemporalExtent from a dict.

Returns:The TemporalExtent deserialized from the JSON dict.
Return type:TemporalExtent
static from_now()[source]

Constructs an TemporalExtent with a single open interval that has the start time as the current time.

Returns:The resulting TemporalExtent.
Return type:TemporalExtent
to_dict()[source]

Generate a dictionary representing the JSON of this TemporalExtent.

Returns:A serializion of the TemporalExtent that can be written out as JSON.
Return type:dict

Provider

class pystac.Provider(name, description=None, roles=None, url=None)[source]

Provides information about a provider of STAC data. A provider is any of the organizations that captured or processed the content of the collection and therefore influenced the data offered by this collection. May also include information about the final storage provider hosting the data.

Parameters:
  • name (str) – The name of the organization or the individual.
  • description (str) – Optional multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information.
  • roles (List[str]) – Optional roles of the provider. Any of licensor, producer, processor or host.
  • url (str) – Optional homepage on which the provider describes the dataset and publishes contact information.
name

The name of the organization or the individual.

Type:str
description

Optional multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information.

Type:str
roles

Optional roles of the provider. Any of licensor, producer, processor or host.

Type:List[str]
url

Optional homepage on which the provider describes the dataset and publishes contact information.

Type:str
static from_dict(d)[source]

Constructs an Provider from a dict.

Returns:The Provider deserialized from the JSON dict.
Return type:TemporalExtent
to_dict()[source]

Generate a dictionary representing the JSON of this Provider.

Returns:A serializion of the Provider that can be written out as JSON.
Return type:dict

Item Spec

These classes are representations of the Item Spec.

Item

class pystac.Item(id, geometry, bbox, datetime, properties, stac_extensions=None, href=None, collection=None, extra_fields=None)[source]

Bases: pystac.stac_object.STACObject

An Item is the core granular entity in a STAC, containing the core metadata that enables any client to search or crawl online catalogs of spatial ‘assets’ - satellite imagery, derived data, DEM’s, etc.

Parameters:
  • id (str) – Provider identifier. Must be unique within the STAC.
  • geometry (dict) – Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).
  • bbox (List[float] or None) – Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array must be 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.
  • datetime (datetime or None) – Datetime associated with this item. If None, a start_datetime and end_datetime must be supplied in the properties.
  • properties (dict) – A dictionary of additional metadata for the item.
  • stac_extensions (List[str]) – Optional list of extensions the Item implements.
  • href (str or None) – Optional HREF for this item, which be set as the item’s self link’s HREF.
  • collection (Collection or str) – The Collection or Collection ID that this item belongs to.
  • extra_fields (dict or None) – Extra fields that are part of the top-level JSON properties of the Item.
id

Provider identifier. Unique within the STAC.

Type:str
geometry

Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).

Type:dict
bbox

Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array is 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.

Type:List[float] or None
datetime

Datetime associated with this item. If None, the start_datetime and end_datetime in the common_metadata will supply the datetime range of the Item.

Type:datetime or None
properties

A dictionary of additional metadata for the item.

Type:dict
stac_extensions

Optional list of extensions the Item implements.

Type:List[str] or None
collection

Collection that this item is a part of.

Type:Collection or None

A list of Link objects representing all links associated with this STACObject.

Type:List[Link]
assets

Dictionary of asset objects that can be downloaded, each with a unique key.

Type:Dict[str, Asset]
collection_id

The Collection ID that this item belongs to, if any.

Type:str or None
extra_fields

Extra fields that are part of the top-level JSON properties of the Item.

Type:dict or None
STAC_OBJECT_TYPE = 'ITEM'
add_asset(key, asset)[source]

Adds an Asset to this item.

Parameters:
  • key (str) – The unique key of this asset.
  • asset (Asset) – The Asset to add.
clone()[source]

Clones this object.

Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use STACObject.full_copy.

Returns:The clone of this object.
Return type:STACObject
common_metadata

Access the item’s common metadat fields as a CommonMetadata object

Returns:contains all common metadata fields in the items properties
Return type:CommonMetada
classmethod from_dict(d, href=None, root=None)[source]

Parses this STACObject from the passed in dictionary.

Parameters:
  • d (dict) – The dict to parse.
  • href (str) – Optional href that is the file location of the object being parsed.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns:

The STACObject parsed from this dict.

Return type:

STACObject

get_assets()[source]

Get this item’s assets.

Returns:A copy of the dictionary of this item’s assets.
Return type:Dict[str, Asset]
get_collection()[source]

Gets the collection of this item, if one exists.

Returns:If this item belongs to a collection, returns a reference to the collection. Otherwise returns None.
Return type:Collection or None
get_datetime(asset=None)[source]

Gets an Item or an Asset datetime.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.

Returns:datetime or None
make_asset_hrefs_absolute()[source]

Modify each asset’s HREF to be absolute.

Any asset HREFs that are relative will be modified to absolute based on this item’s self HREF.

Returns:self
Return type:Item
make_asset_hrefs_relative()[source]

Modify each asset’s HREF to be relative to this item’s self HREF.

Returns:self
Return type:Item
set_collection(collection)[source]

Set the collection of this item.

This method will replace any existing Collection link and attribute for this item.

Parameters:collection (Collection or None) – The collection to set as this item’s collection. If None, will clear the collection.
Returns:self
Return type:Item
set_datetime(datetime, asset=None)[source]

Set an Item or an Asset datetime.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_self_href(href)[source]

Sets the absolute HREF that is represented by the rel == 'self' Link.

Changing the self HREF of the item will ensure that all asset HREFs remain valid. If asset HREFs are relative, the HREFs will change to point to the same location based on the new item self HREF, either by making them relative to the new location or making them absolute links if the new location does not share the same protocol as the old location.

Parameters:href (str) – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.
to_dict(include_self_link=True)[source]

Generate a dictionary representing the JSON of this serialized object.

Parameters:include_self_link (bool) – If True, the dict will contain a self link to this object. If False, the self link will be omitted.
Returns:A serializion of the object that can be written out as JSON.
Return type:dict

Asset

class pystac.Asset(href, title=None, description=None, media_type=None, roles=None, properties=None)[source]

An object that contains a link to data associated with the Item that can be downloaded or streamed.

Parameters:
  • href (str) – Link to the asset object. Relative and absolute links are both allowed.
  • title (str) – Optional displayed title for clients and users.
  • description (str) – A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.
  • media_type (str) – Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.
  • roles ([str]) – Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the asset.
  • properties (dict) – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
href

Link to the asset object. Relative and absolute links are both allowed.

Type:str
title

Optional displayed title for clients and users.

Type:str
description

A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

Type:str
media_type

Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.

Type:str
properties

Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

Type:dict
owner

The Item this asset belongs to.

Type:Item or None
clone()[source]

Clones this asset.

Returns:The clone of this asset.
Return type:Asset
static from_dict(d)[source]

Constructs an Asset from a dict.

Returns:The Asset deserialized from the JSON dict.
Return type:Asset
get_absolute_href()[source]

Gets the absolute href for this asset, if possible.

If this Asset has no associated Item, this will return whatever the href is (as it cannot determine the absolute path, if the asset href is relative).

Returns:The absolute HREF of this asset, or a relative HREF is an abslolute HREF cannot be determined.
Return type:str
set_owner(item)[source]

Sets the owning item of this Asset.

The owning item will be used to resolve relative HREFs of this asset.

Parameters:item (Item) – The Item that owns this asset.
to_dict()[source]

Generate a dictionary representing the JSON of this Asset.

Returns:A serializion of the Asset that can be written out as JSON.
Return type:dict

CommonMetadata

class pystac.CommonMetadata(properties)[source]

Object containing fields that are not included in core item schema but are still commonly used. All attributes are defined within the properties of this item and are optional

Parameters:properties (dict) – Dictionary of attributes that is the Item’s properties
constellation

Get or set the name of the constellation associate with an item

Returns:Name of the constellation to which the platform belongs
Return type:str
created

Get or set the metadata file’s creation date. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string

Returns:Creation date and time of the metadata file
Return type:datetime
description

Get or set the item’s description

Returns:Detailed description of the item
Return type:str
end_datetime

Get or set the item’s end_datetime. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string

Returns:End date and time for the item
Return type:datetime
get_constellation(asset=None)[source]

Gets an Item or an Asset constellation.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
get_created(asset=None)[source]

Gets an Item or an Asset created time.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.

Note

created and updated have different meaning depending on where they are used. If those fields are available in the Item properties, it’s referencing to the creation and update times of the metadata. Having those fields in the Item assets refers to the creation and update times of the actual data linked to in the Asset Object.

Returns:datetime
get_end_datetime(asset=None)[source]

Gets an Item or an Asset end_datetime.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:datetime
get_gsd(asset=None)[source]

Gets an Item or an Asset gsd.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
get_instruments(asset=None)[source]

Gets an Item or an Asset instruments.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[str]
get_license(asset=None)[source]

Gets an Item or an Asset license.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
get_mission(asset=None)[source]

Gets an Item or an Asset mission.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
get_platform(asset=None)[source]

Gets an Item or an Asset platform.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
get_providers(asset=None)[source]

Gets an Item or an Asset providers.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[Provider]
get_start_datetime(asset=None)[source]

Gets an Item or an Asset start_datetime.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:datetime
get_updated(asset=None)[source]

Gets an Item or an Asset updated time.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.

Note

created and updated have different meaning depending on where they are used. If those fields are available in the Item properties, it’s referencing to the creation and update times of the metadata. Having those fields in the Item assets refers to the creation and update times of the actual data linked to in the Asset Object.

Returns:datetime
gsd

Get or sets the Ground Sample Distance at the sensor.

Returns:Ground Sample Distance at the senso
Return type:[float]
instruments

Get or set the names of the instruments used

Returns:Name(s) of instrument(s) used
Return type:List[str]
license

Get or set the current license

Returns:Item’s license(s), either SPDX identifier of ‘various’
Return type:str
mission

Get or set the name of the mission associated with an item

Returns:Name of the mission in which data are collected
Return type:str
platform

Get or set the item’s platform attribute

Returns:Unique name of the specific platform to which the instrument is attached
Return type:str
providers

Get or set a list of the item’s providers. The setter can take either a Provider object or a dict but always stores each provider as a dict

Returns:List of organizations that captured or processed the data, encoded as Provider objects
Return type:List[Provider]
set_constellation(constellation, asset=None)[source]

Set an Item or an Asset constellation.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_created(created, asset=None)[source]

Set an Item or an Asset created time.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_end_datetime(end_datetime, asset=None)[source]

Set an Item or an Asset end_datetime.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_gsd(gsd, asset=None)[source]

Set an Item or an Asset gsd.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_instruments(instruments, asset=None)[source]

Set an Item or an Asset instruments.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_license(license, asset=None)[source]

Set an Item or an Asset license.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_mission(mission, asset=None)[source]

Set an Item or an Asset mission.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_platform(platform, asset=None)[source]

Set an Item or an Asset platform.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_providers(providers, asset=None)[source]

Set an Item or an Asset providers.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_start_datetime(start_datetime, asset=None)[source]

Set an Item or an Asset start_datetime.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_updated(updated, asset=None)[source]

Set an Item or an Asset updated time.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

start_datetime

Get or set the item’s start_datetime. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string

Returns:Start date and time for the item
Return type:datetime
title

Get or set the item’s title

Returns:Human readable title describing the item
Return type:str
updated

Get or set the metadata file’s update date. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string

Note

created and updated have different meaning depending on where they are used. If those fields are available in the Item properties, it’s referencing to the creation and update times of the metadata. Having those fields in the Item assets refers to the creation and update times of the actual data linked to in the Asset Object.

Returns:
Date and time that the metadata file was most recently
updated
Return type:datetime

IO

STAC_IO

STAC_IO is the utility mechanism that PySTAC uses for reading and writing. Users of PySTAC can hook into PySTAC by overriding members to utilize their own IO methods.

class pystac.STAC_IO[source]

Methods used to read and save STAC json. Allows users of the library to set their own methods (e.g. for reading and writing from cloud storage)

default_read_text_method()[source]

Default method for reading text. Only handles local file paths.

default_write_text_method(txt)[source]

Default method for writing text. Only handles local file paths.

classmethod read_json(uri)[source]

Read a dict from the given URI.

Parameters:uri (str) – The URI from which to read.
Returns:A dict representation of the JSON contained in the file at the given uri.
Return type:dict

Note

This method uses the STAC_IO.read_text_method. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.

classmethod read_stac_object(uri, root=None)[source]

Read a STACObject from a JSON file at the given URI.

Parameters:
  • uri (str) – The URI from which to read.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
Returns:

The deserialized STACObject from the serialized JSON contained in the file at the given uri.

Return type:

STACObject

Note

This method uses the STAC_IO.read_text_method. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.

classmethod read_text(uri)[source]

Read text from the given URI.

Parameters:uri (str) – The URI from which to read text.
Returns:The text contained in the file at the location specified by the uri.
Return type:str

Note

This method uses the STAC_IO.read_text_method. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.

read_text_method()

Users of PySTAC can replace the read_text_method in order to expand the ability of PySTAC to read different file systems. For example, a client of the library might replace this class member in it’s own __init__.py with a method that can read from cloud storage.

classmethod save_json(uri, json_dict)[source]

Write a dict to the given URI as JSON.

Parameters:
  • uri (str) – The URI of the file to write the text to.
  • json_dict (dict) – The JSON dict to write.

Note

This method uses the STAC_IO.write_text_method. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.

stac_object_from_dict(href=None, root=None)

Determines how to deserialize a dictionary into a STAC object.

Parameters:
  • d (dict) – The dict to parse.
  • href (str) – Optional href that is the file location of the object being parsed.
  • root (Catalog or Collection) – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.

Note: This is used internally in STAC_IO to deserialize STAC Objects. It is in the top level __init__ in order to avoid circular dependencies.

classmethod write_text(uri, txt)[source]

Write the given text to a file at the given URI.

Parameters:
  • uri (str) – The URI of the file to write the text to.
  • txt (str) – The text to write.

Note

This method uses the STAC_IO.write_text_method. If you want to modify the behavior of STAC_IO in order to enable additional URI types, replace that member with your own implementation.

write_text_method(txt)

Users of PySTAC can replace the writte_text_method in order to expand the ability of PySTAC to write to different file systems. For example, a client of the library might replace this class member in it’s own __init__.py with a method that can read from cloud storage.

Layout

These classes are used to set the HREFs of a STAC according to some layout. The templating functionality is also used when generating subcatalogs based on a template.

Templating

class pystac.layout.LayoutTemplate(template, defaults=None)[source]

Represents a template that can be used for deriving paths or other information based on properties of STAC objects supplied as a template string.

Template strings use variables that can be pulled out of Catalogs, Collections and Items. The variable names can represent properties on the object itself, or keys in the dictionaries of the properties or extra_fields on the object (if they exist). The search order is as follows:

  • The object’s attributes
  • Keys in the properties attribute, if it exists.
  • Keys in the extra_fields attribute, if it exists.

Some special keys can be used in template variables:

Template variable Meaning
year The year of an Item’s datetime, or start_datetime if datetime is null
month The month of an Item’s datetime, or start_datetime if datetime is null
day The day of an Item’s datetime, or start_datetime if datetime is null
date The date (iso format) of an Item’s datetime, or start_datetime if datetime is null
collection The collection ID of an Item’s collection.

Examples:

# Uses the year, month and day of the item
template = LayoutTemplate("${year}/${month}/${day}")

# Uses a custom extension properties found on in the item properties.
template = LayoutTemplate("${landsat:path}/${landsat:row}")

# Uses the collection ID and a common metadata property for an item.
template = LayoutTemplate("${collection}/${common_metadata.license}")
Parameters:
  • template (str) – The template string to use.
  • defaults (dict) – A dictionary of template vars to values. These values will be used in case a value cannot be derived from a stac object.
get_template_values(stac_object)[source]

Gets a dictionary of template variables to values derived from the given stac_object. If the template vars cannot be found in the stac object, and defaults was supplied to this template, a default value is used; if there is no default then this will raise an error.

Parameters:stac_object (STACObject) – The STACObject to derive template variable values from.
Returns:
A dictionary with keys being the template variables
and values being the respective values based on the given stac object.
Return type:[dict]
Raises:TemplateError – If a value for a template variable cannot be derived from the stac object and there is no default, this error will be raised.
substitute(stac_object)[source]

Substitutes the values derived from get_template_values() into the template string for this template.

Parameters:stac_object (STACObject) – The STACObject to derive template variable values from.
Returns:
The original template supplied to this LayoutTemplate
with template variables replaced by the values derived from this stac object.
Return type:[str]
Raises:TemplateError – If a value for a template variable cannot be derived from the stac object and there is no default, this error will be raised.
class pystac.layout.TemplateError[source]

Exception thrown when an error occurs during converting a template string into data for LayoutTemplate

HREF Layout Strategies

class pystac.layout.BestPracticesLayoutStrategy[source]

Layout strategy that represents the catalog layout described in the STAC Best Practices documentation

For a root catalog or collection, this will use the filename ‘catalog.json’ or ‘collection.json’ to the given directory. For a non-root catalog or collection, the ID will be used as a subdirectory, e.g. ${id}/catalog.json or ${id}/collection.json. For items, a subdirectory with a name of the item ID will be made, and the item ID will be used in the filename, i.e. ${id}/${id}.json

All paths are appended to the parent directory.

class pystac.layout.TemplateLayoutStrategy(catalog_template=None, collection_template=None, item_template=None, fallback_strategy=None)[source]

Layout strategy that can take strings to be supplied to LayoutTemplate s to derive paths. Template strings can be supplied for catalogs, collections and items separately. If no template is supplied, a fallback layout strategy is supplied, which defaults to the BestPracticesLayoutStrategy.

All templated paths will be joined with the parent directory of the stac object.

Parameters:
  • catalog_template (str) – The template string to use for catalog paths. Must be a valid template string that can be used by LayoutTemplate
  • collection_template (str) – The template string to use for collection paths. Must be a valid template string that can be used by LayoutTemplate
  • item_template (str) – The template string to use for item paths. Must be a valid template string that can be used by LayoutTemplate
  • fallback_strategy (HrefLayoutStrategy) – The fallback strategy to use if a template is not provided. Defaults to BestPracticesLayoutStrategy
class pystac.layout.CustomLayoutStrategy(catalog_func=None, collection_func=None, item_func=None, fallback_strategy=None)[source]

Layout strategy that allows users to supply functions to dictate stac object paths.

Parameters:
  • catalog_func (Callable[Catalog, str, bool] -> str) – A function that takes an catalog, a parent directory, and a flag specifying whether or not this catalog is the root. If it is the root, its usually best to not create a subdirectory and put the Catalog file directly in the parent directory. Must return the string path.
  • collection_func (Callable[Catalog, str, bool] -> str) – A function that is used for collections in the same manner at catalog_func. This takes the same parameters.
  • item_func (Callable[Catalog, str] -> str) – A function that takes an item and a parent directory and returns the path to be used for the item.
  • fallback_strategy (HrefLayoutStrategy) – The fallback strategy to use if a function is not provided for a stac object type. Defaults to BestPracticesLayoutStrategy

Errors

STACError

class pystac.STACError[source]

A STACError is raised for errors relating to STAC, e.g. for invalid formats or trying to operate on a STAC that does not have the required information available.

ExtensionError

class pystac.extensions.ExtensionError[source]

An error related to the construction of extensions.

Extensions

class pystac.extensions.Extensions[source]

Enumerates the IDs of common extensions.

CHECKSUM = 'checksum'
COLLECTION_ASSETS = 'collection-assets'
DATACUBE = 'datacube'
EO = 'eo'
FILE = 'file'
ITEM_ASSETS = 'item-assets'
LABEL = 'label'
POINTCLOUD = 'pointcloud'
PROJECTION = 'projection'
SAR = 'sar'
SAT = 'sat'
SCIENTIFIC = 'scientific'
SINGLE_FILE_STAC = 'single-file-stac'
TILED_ASSETS = 'tiled-assets'
TIMESTAMPS = 'timestamps'
VERSION = 'version'
VIEW = 'view'

ExtensionIndex

An ExtensionIndex is accessed through the STACObject.ext property and is the primary way to access information and functionality around STAC extensions.

class pystac.stac_object.ExtensionIndex(stac_object)[source]

Defines methods for accessing extension functionality.

To access a specific extension, use the __getitem__ on this class with the extension ID:

# Access the "bands" property on the eo extension.
item.ext['eo'].bands
__getattr__(extension_id)[source]

Gets an extension based on a dynamic attribute.

This takes the attribute name and passes it to __getitem__.

This allows the following two lines to be equivalent:

item.ext["label"].label_properties
item.ext.label.label_properties
__getitem__(extension_id)[source]

Gets the extension object for the given extension.

Returns:The extension object through which you can access the extension functionality for the extension represented by the extension_id.
Return type:CatalogExtension or CollectionExtension or ItemExtension
enable(extension_id)[source]

Enables a stac extension for the given object. If the object already enables the extension, no action is taken. If it does not, the extension ID is added to the object’s stac_extension property.

Parameters:
  • extension_id (str) – The extension ID representing the extension
  • object should implement (the) –
implements(extension_id)[source]

Returns true if the associated object implements the given extension.

Parameters:extension_id (str) – The extension ID to check
Returns:
True if the object implements the extensions - i.e. if
the extension ID is in the “stac_extensions” property.
Return type:[bool]

EO Extension

These classes are representations of the EO Extension Spec.

EOItemExt

class pystac.extensions.eo.EOItemExt(item)[source]

Bases: pystac.extensions.base.ItemExtension

EOItemExt is the extension of the Item in the eo extension which represents a snapshot of the earth for a single date and time.

Parameters:item (Item) – The item to be extended.
item

The Item that is being extended.

Type:Item

Note

Using EOItemExt to directly wrap an item will add the ‘eo’ extension ID to the item’s stac_extensions.

apply(bands, cloud_cover=None)[source]

Applies label extension properties to the extended Item.

Parameters:
  • bands (List[Band]) – a list of Band objects that represent the available bands.
  • cloud_cover (float or None) – The estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.
bands
Get or sets a list of Band objects that represent
the available bands.
Returns:List[Band]
cloud_cover
Get or sets the estimate of cloud cover as a percentage (0-100) of the
entire scene. If not available the field should not be provided.
Returns:float or None
classmethod from_item(item)[source]
get_bands(asset=None)[source]

Gets an Item or an Asset bands.

If an Asset is supplied and the bands property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value or all the asset’s eo bands

Returns:List[Band]
get_cloud_cover(asset=None)[source]

Gets an Item or an Asset cloud_cover.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
set_bands(bands, asset=None)[source]

Set an Item or an Asset bands.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_cloud_cover(cloud_cover, asset=None)[source]

Set an Item or an Asset cloud_cover.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

Band

class pystac.extensions.eo.Band(properties)[source]

Represents Band information attached to an Item that implements the eo extension.

Use Band.create to create a new Band.

apply(name, common_name=None, description=None, center_wavelength=None, full_width_half_max=None)[source]

Sets the properties for this Band.

Parameters:
  • name (str) – The name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).
  • common_name (str) – The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.
  • description (str) – Description to fully explain the band.
  • center_wavelength (float) – The center wavelength of the band, in micrometers (μm).
  • full_width_half_max (float) – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).
static band_description(common_name)[source]

Returns a description of the band for one with a common name.

Parameters:common_name (str) –

The common band name. Must be one of the list of accepted common names.

Returns:If a recognized common name, returns a description including the band range. Otherwise returns None.
Return type:str or None
static band_range(common_name)[source]

Gets the band range for a common band name.

Parameters:common_name (str) –

The common band name. Must be one of the list of accepted common names.

Returns:The band range for this name as (min, max), or None if this is not a recognized common name.
Return type:Tuple[float, float] or None
center_wavelength

Get or sets the center wavelength of the band, in micrometers (μm).

Returns:float
common_name
Get or sets the name commonly used to refer to the band to make it easier
to search for bands across instruments. See the list of accepted common names.
Returns:str
classmethod create(name, common_name=None, description=None, center_wavelength=None, full_width_half_max=None)[source]

Creates a new band.

Parameters:
  • name (str) – The name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).
  • common_name (str) –

    The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.

  • description (str) – Description to fully explain the band.
  • center_wavelength (float) – The center wavelength of the band, in micrometers (μm).
  • full_width_half_max (float) – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).
description

Get or sets the description to fully explain the band. CommonMark 0.29 syntax MAY be used for rich text representation.

Returns:str
full_width_half_max
Get or sets the full width at half maximum (FWHM). The width of the band,
as measured at half the maximum transmission, in micrometers (μm).
Returns:[float]
name

Get or sets the name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).

Returns:str
to_dict()[source]

Returns the dictionary representing the JSON of this Band.

Returns:The wrapped dict of the Band that can be written out as JSON.
Return type:dict

Label Extension

These classes are representations of the Label Extension Spec.

LabelItemExt

class pystac.extensions.label.LabelItemExt(item)[source]

Bases: pystac.extensions.base.ItemExtension

A LabelItemExt is the extension of the Item in the label extension which represents a polygon, set of polygons, or raster data defining labels and label metadata and should be part of a Collection.

Parameters:item (Item) – The item to be extended.
item

The Item that is being extended.

Type:Item
See:
Item fields in the label extension spec

Note

Using LabelItemExt to directly wrap an item will add the ‘label’ extension ID to the item’s stac_extensions.

add_geojson_labels(href, title=None, properties=None)[source]

Adds a GeoJSON label asset to this LabelItem.

Parameters:
  • href (str) – Link to the asset object. Relative and absolute links are both allowed.
  • title (str) – Optional displayed title for clients and users.
  • properties (dict) – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
add_labels(href, title=None, media_type=None, properties=None)[source]

Adds a label asset to this LabelItem.

Parameters:
  • href (str) – Link to the asset object. Relative and absolute links are both allowed.
  • title (str) – Optional displayed title for clients and users.
  • media_type (str) – Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.
  • properties (dict) – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.
add_source(source_item, title=None, assets=None)[source]

Adds a link to a source item.

Parameters:
  • source_item (Item) – Source imagery that the LabelItem applies to.
  • title (str) – Optional title for the link.
  • assets (List[str]) – Optional list of assets that determine what assets in the source item this label item data applies to.
apply(label_description, label_type, label_properties=None, label_classes=None, label_tasks=None, label_methods=None, label_overviews=None)[source]

Applies label extension properties to the extended Item.

Parameters:
  • label_description (str) – A description of the label, how it was created, and what it is recommended for
  • label_type (str) – An ENUM of either vector label type or raster label type. Use one of LabelType.
  • label_properties (list or None) – These are the names of the property field(s) in each Feature of the label asset’s FeatureCollection that contains the classes (keywords from label:classes if the property defines classes). If labels are rasters, this should be None.
  • label_classes (List[LabelClass]) – Optional, but reqiured if ussing categorical data. A list of LabelClasses defining the list of possible class names for each label:properties. (e.g., tree, building, car, hippo)
  • label_tasks (List[str]) – Recommended to be a subset of ‘regression’, ‘classification’, ‘detection’, or ‘segmentation’, but may be an arbitrary value.
  • label_methods – Recommended to be a subset of ‘automated’ or ‘manual’, but may be an arbitrary value.
  • label_overviews (List[LabelOverview]) – Optional list of LabelOverview classes that store counts (for classification-type data) or summary statistics (for continuous numerical/regression data).
classmethod from_item(item)[source]
get_sources()[source]

Gets any source items that describe the source imagery used to generate this LabelItem.

Returns:A possibly empty list of source imagery items. Determined by links of this LabelItem that have rel=='source'.
Return type:Generator[Items]
label_classes

Get or set a list of LabelClasses defining the list of possible class names for each label:properties. (e.g., tree, building, car, hippo).

Optional, but reqiured if using categorical data.

Returns:List[LabelClasses] or None
label_description

Get or sets a description of the label, how it was created, and what it is recommended for.

Returns:str
label_methods
Get or set a list of methods used for labeling. Usually a subset of ‘automated’ or ‘manual’,
but may be arbitrary values.
Returns:List[str] or None
label_overviews

Get or set a list of LabelOverview classes that store counts (for classification-type data) or summary statistics (for continuous numerical/regression data).

Returns:List[LabelOverview] or None
label_properties

Label Properties

Gets or sets the names of the property field(s) in each Feature of the label asset’s FeatureCollection that contains the classes (keywords from label:classes if the property defines classes). If labels are rasters, this should be None.

Returns:List[str] or None
label_tasks
Get or set a list of tasks these labels apply to. Usually a subset of ‘regression’,
‘classification’, ‘detection’, or ‘segmentation’, but may be arbitrary values.
Returns:List[str] or None
label_type

Gets or sets an ENUM of either vector label type or raster label type (one of LabelType).

Returns:str

LabelType

class pystac.extensions.label.LabelType[source]

Enumerates valid label types (RASTER or VECTOR).

ALL = "['vector', 'raster']"

Convenience attribute for checking if values are valid label types

RASTER = 'raster'
VECTOR = 'vector'

LabelClasses

class pystac.extensions.label.LabelClasses(properties)[source]

Defines the list of possible class names (e.g., tree, building, car, hippo)

Use LabelClasses.create to create a new instance of LabelClasses from property values.

apply(classes, name=None)[source]

Sets the properties for this LabelClasses.

Parameters:
  • classes (List[str] or List[int] or List[float]) – The different possible class values.
  • name (str) – The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.
classes

Get or sets the class values.

Returns:List[str] or List[int] or List[float]
classmethod create(classes, name=None)[source]

Creates a new LabelClasses.

Parameters:
  • classes (List[str] or List[int] or List[float]) – The different possible class values.
  • name (str) – The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.
Returns:

LabelClasses

name

Get or sets the property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.

Returns:str
to_dict()[source]

Returns the dictionary representing the JSON of this LabelClasses.

Returns:The wrapped dict of the LabelClasses that can be written out as JSON.
Return type:dict

LabelOverview

class pystac.extensions.label.LabelOverview(properties)[source]

Stores counts (for classification-type data) or summary statistics (for continuous numerical/regression data).

Use LabelOverview.create to create a new LabelOverview.

apply(property_key, counts=None, statistics=None)[source]

Sets the properties for this LabelOverview.

Either counts or statistics, or both, can be placed in an overview; at least one is required.

Parameters:
  • property_key (str) – The property key within the asset corresponding to class labels.
  • counts (List[LabelCounts]) – Optional list of LabelCounts containing counts for categorical data.
  • statistics (List[Statistics]) – Optional list of Statistics containing statistics for regression/continuous numeric value data.
counts

Get or sets the list of LabelCounts containing counts for categorical data.

Returns:List[LabelCount]
classmethod create(property_key, counts=None, statistics=None)[source]

Creates a new LabelOverview.

Either counts or statistics, or both, can be placed in an overview; at least one is required.

Parameters:
  • property_key (str) – The property key within the asset corresponding to class labels.
  • counts (List[LabelCounts]) – Optional list of LabelCounts containing counts for categorical data.
  • statistics (List[Statistics]) – Optional list of Statistics containing statistics for regression/continuous numeric value data.
merge_counts(other)[source]

Merges the counts associated with this overview with another overview. Creates a new LabelOverview.

Parameters:other (LabelOverview) – The other LabelOverview to merge.
Returns:A new LabelOverview with the counts merged. This will drop any statistics associated with either of the LabelOverviews.
Return type:LabelOverview
property_key

Get or sets the property key within the asset corresponding to class labels.

Returns:str
statistics

Get or sets the list of Statistics containing statistics for regression/continuous numeric value data.

Returns:List[Statistics]
to_dict()[source]

Returns the dictionary representing the JSON of this LabelOverview.

Returns:The wrapped dict of the LabelOverview that can be written out as JSON.
Return type:dict

LabelCount

class pystac.extensions.label.LabelCount(properties)[source]

Contains counts for categorical data.

Use LabelCount.create to create a new LabelCount

apply(name, count)[source]

Sets the properties for this LabelCount.

Parameters:
  • name (str) – One of the different possible classes within the property.
  • count (int) – The number of occurrences of the class.
count

Get or sets the number of occurrences of the class.

Returns:int
classmethod create(name, count)[source]

Creates a LabelCount.

Parameters:
  • name (str) – One of the different possible classes within the property.
  • count (int) – The number of occurrences of the class.
name

Get or sets the class that this count represents.

Returns:str
to_dict()[source]

Returns the dictionary representing the JSON of this LabelCount.

Returns:The wrapped dict of the LabelCount that can be written out as JSON.
Return type:dict

LabelStatistics

class pystac.extensions.label.LabelStatistics(properties)[source]

Contains statistics for regression/continuous numeric value data.

Use LabelStatistics.create to create a new instance.

apply(name, value)[source]

Sets the property values for this instance.

Parameters:
  • name (str) – The name of the statistic being reported.
  • value (float) – The value of the statistic
classmethod create(name, value)[source]

Sets the property values for this instance.

Parameters:
  • name (str) – The name of the statistic being reported.
  • value (float) – The value of the statistic
name

Get or sets the name of the statistic being reported.

Returns:str
to_dict()[source]

Returns the dictionary representing the JSON of this LabelStatistics.

Returns:The wrapped dict of the LabelStatistics that can be written out as JSON.
Return type:dict
value

Get or sets the value of the statistic

Returns:int or float

Pointcloud Extension

Implements the Point Cloud Extension.

PointcloudItemExt

class pystac.extensions.pointcloud.PointcloudItemExt(item)[source]

Bases: pystac.extensions.base.ItemExtension

PointcloudItemExt is the extension of an Item in the PointCloud Extension. The Pointclout extension adds pointcloud information to STAC Items.

Parameters:item (Item) – The item to be extended.
item

The Item that is being extended.

Type:Item
apply(count, type, encoding, schemas, density=None, statistics=None, epsg=None)[source]

Applies Pointcloud extension properties to the extended Item.

Parameters:
  • count (int) – REQUIRED. The number of points in the cloud.
  • type (str) – REQUIRED. Phenomenology type for the point cloud. Possible valid values might include lidar, eopc, radar, sonar, or otherThe type of file or data format of the cloud.
  • encoding (str) – REQUIRED. Content encoding or format of the data.
  • schemas (List[dict]) – REQUIRED. A sequential array of items that define the dimensions and their types.
  • density (dict or None) – Number of points per square unit area.
  • statistics (List[int] or None) – A sequential array of items mapping to pc:schemas defines per-channel statistics.
  • epsg (str) – An EPSG code for the projected coordinates of the pointcloud.
count

Get or sets the count property of the datasource.

Returns:int
density

Get or sets the density for the item.

Density is defined as the number of points per square unit area.

Returns:int
encoding

Get or sets the content-encoding for the item.

The content-encoding is the underlying encoding format for the point cloud. Examples may include: laszip, ascii, binary, etc.

Returns:str
classmethod from_item(item)[source]
get_count(asset=None)[source]

Gets an Item or an Asset count.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:int
get_density(asset=None)[source]

Gets an Item or an Asset density.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:int
get_encoding(asset=None)[source]

Gets an Item or an Asset encoding.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
get_schemas(asset=None)[source]

Gets an Item or an Asset projection geometry.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[PointcloudSchema]
get_statistics(asset=None)[source]

Gets an Item or an Asset centroid.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[PointCloudStatistics] or None
get_type(asset=None)[source]

Gets an Item or an Asset type.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
schemas

Get or sets a

The schemas represent the structure of the data attributes in the pointcloud, and is represented as a sequential array of items that define the dimensions and their types,

Returns:List[PointcloudSchema]
set_count(count, asset=None)[source]

Set an Item or an Asset count.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_density(density, asset=None)[source]

Set an Item or an Asset density property.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_encoding(encoding, asset=None)[source]

Set an Item or an Asset encoding.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_schemas(schemas, asset=None)[source]

Set an Item or an Asset schema

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_statistics(statistics, asset=None)[source]

Set an Item or an Asset centroid.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_type(type, asset=None)[source]

Set an Item or an Asset type.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

statistics

Get or sets the statistics for each property of the dataset.

A sequential array of items mapping to pc:schemas defines per-channel statistics.

Example:

item.ext.pointcloud.statistics = [{ 'name': 'red', 'min': 0, 'max': 255 }]
Returns:List[dict]
type

type prop on the Item

Returns:str
Type:Get or sets the pc

Projection Extension

Implements the Projection Extension.

ProjectionItemExt

class pystac.extensions.projection.ProjectionItemExt(item)[source]

Bases: pystac.extensions.base.ItemExtension

ProjectionItemExt is the extension of an Item in the Projection Extension. The Projection extension adds projection information to STAC Items.

Parameters:item (Item) – The item to be extended.
item

The Item that is being extended.

Type:Item

Note

Using ProjectionItemExt to directly wrap an item will add the ‘proj’ extension ID to the item’s stac_extensions.

apply(epsg, wkt2=None, projjson=None, geometry=None, bbox=None, centroid=None, shape=None, transform=None)[source]

Applies Projection extension properties to the extended Item.

Parameters:
  • epsg (int or None) – REQUIRED. EPSG code of the datasource.
  • wkt2 (str or None) – WKT2 string representing the Coordinate Reference System (CRS) that the geometry and bbox fields represent
  • projjson (dict or None) – PROJJSON dict representing the Coordinate Reference System (CRS) that the geometry and bbox fields represent
  • geometry (dict or None) – GeoJSON Polygon dict that defines the footprint of this Item.
  • bbox (List[float] or None) – Bounding box of the Item in the asset CRS in 2 or 3 dimensions.
  • centroid (dict or None) – A dict with members ‘lat’ and ‘lon’ that defines coordinates representing the centroid of the item in the asset data CRS. Coordinates are defined in latitude and longitude, even if the data coordinate system may not use lat/long.
  • shape (List[int] or None) – Number of pixels in Y and X directions for the default grid.
  • transform (List[float] or None) – The affine transformation coefficients for the default grid
bbox

Get or sets the bounding box of the assets represented by this item in the asset data CRS.

Specified as 4 or 6 coordinates based on the CRS defined in the epsg, projjson or wkt2 properties. First two numbers are coordinates of the lower left corner, followed by coordinates of upper right corner, e.g., [west, south, east, north], [xmin, ymin, xmax, ymax], [left, down, right, up], or [west, south, lowest, east, north, highest]. The length of the array must be 2*n where n is the number of dimensions.

Returns:List[float]
centroid

Get or sets coordinates representing the centroid of the item in the asset data CRS.

Coordinates are defined in latitude and longitude, even if the data coordinate system does not use lat/long.

Exmample:

item.ext.proj.centroid = { 'lat': 0.0, 'lon': 0.0 }
Returns:dict
epsg

Get or sets the EPSG code of the datasource.

A Coordinate Reference System (CRS) is the data reference system (sometimes called a ‘projection’) used by the asset data, and can usually be referenced using an EPSG code. If the asset data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, epsg should be set to None. It should also be set to null if a CRS exists, but for which there is no valid EPSG code.

Returns:int
classmethod from_item(item)[source]
geometry

Get or sets a Polygon GeoJSON dict representing the footprint of this item.

This dict should be formatted according the Polygon object format specified in RFC 7946, sections 3.1.6, except not necessarily in EPSG:4326 as required by RFC7946. Specified based on the epsg, projjson or wkt2 fields (not necessarily EPSG:4326). Ideally, this will be represented by a Polygon with five coordinates, as the item in the asset data CRS should be a square aligned to the original CRS grid.

Returns:dict
get_bbox(asset=None)[source]

Gets an Item or an Asset projection bbox.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[float]
get_centroid(asset=None)[source]

Gets an Item or an Asset centroid.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:dict
get_epsg(asset=None)[source]

Gets an Item or an Asset epsg.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:int
get_geometry(asset=None)[source]

Gets an Item or an Asset projection geometry.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:dict
get_projjson(asset=None)[source]

Gets an Item or an Asset projjson.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:dict
get_shape(asset=None)[source]

Gets an Item or an Asset shape.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[int]
get_transform(asset=None)[source]

Gets an Item or an Asset transform.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:List[float]
get_wkt2(asset=None)[source]

Gets an Item or an Asset wkt2.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:str
projjson

Get or sets the PROJJSON string representing the Coordinate Reference System (CRS) that the proj:geometry and proj:bbox fields represent

This value is a PROJJSON object. If the data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, projjson should be set to null. It should also be set to null if a CRS exists, but for which a PROJJSON string does not exist.

The schema for this object can be found here.

Returns:dict
set_bbox(bbox, asset=None)[source]

Set an Item or an Asset projection bbox.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_centroid(centroid, asset=None)[source]

Set an Item or an Asset centroid.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_epsg(epsg, asset=None)[source]

Set an Item or an Asset epsg.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_geometry(geometry, asset=None)[source]

Set an Item or an Asset projection geometry.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_projjson(projjson, asset=None)[source]

Set an Item or an Asset projjson.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_shape(shape, asset=None)[source]

Set an Item or an Asset shape.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_transform(transform, asset=None)[source]

Set an Item or an Asset transform.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_wkt2(wkt2, asset=None)[source]

Set an Item or an Asset wkt2.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

shape

Get or sets the number of pixels in Y and X directions for the default grid.

The shape is an array of integers that represents the number of pixels in the most common pixel grid used by the item’s assets. The number of pixels should be specified in Y, X order. If the shape is defined in an item’s properties it is used as the default shape for all assets that don’t have an overriding shape.

Returns:List[int]
transform

Get or sets the the affine transformation coefficients for the default grid.

The transform is a linear mapping from pixel coordinate space (Pixel, Line) to projection coordinate space (Xp, Yp). It is a 3x3 matrix stored as a flat array of 9 elements in row major order. Since the last row is always 0,0,1 it can be omitted, in which case only 6 elements are recorded. This mapping can be obtained from GDAL GetGeoTransform or the Rasterio Transform.

Returns:List[float]
wkt2

Get or sets the WKT2 string representing the Coordinate Reference System (CRS) that the proj:geometry and proj:bbox fields represent

This value is a WKT2 string. If the data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points, wkt2 should be set to null. It should also be set to null if a CRS exists, but for which a WKT2 string does not exist.

Returns:str

Timestamps Extension

Implements the Timestamps Extension.

TimestampsItemExt

class pystac.extensions.timestamps.TimestampsItemExt(item)[source]

Bases: pystac.extensions.base.ItemExtension

TimestampsItemExt is the extension of an Item in that allows to specify additional timestamps for assets and metadata.

Parameters:item (Item) – The item to be extended.
item

The Item that is being extended.

Type:Item

Note

Using TimestampsItemExt to directly wrap an item will add the ‘timestamps’ extension ID to the item’s stac_extensions.

apply(published=None, expires=None, unpublished=None)[source]

Applies timestamps extension properties to the extended Item.

Parameters:
  • published (datetime or None) – Date and time the corresponding data was published the first time.
  • expires (datetime or None) – Date and time the corresponding data expires (is not valid any longer).
  • unpublished (datetime or None) – Date and time the corresponding data was unpublished.
expires
Get or sets a datetime objects that represent
the date and time the corresponding data expires (is not valid any longer).
Returns:datetime
classmethod from_item(item)[source]
get_expires(asset=None)[source]

Get an Item or Asset expires datetime

If an Asset is supplied and the expires property exists on the Asset, return the Asset’s value. Otherwise return the Item’s value. ‘Unpublished’ has a different meaning depending on where it is used. If available in the asset properties, it refers to the timestamps valid for the actual data linked to the Asset Object. If it comes from the Item properties, it’s referencing to the timestamp valid for the metadata.

Returns:datetime
get_published(asset=None)[source]

Get an Item or Asset published datetime

If an Asset is supplied and the published property exists on the Asset, return the Asset’s value. Otherwise return the Item’s value. ‘Published’ has a different meaning depending on where it is used. If available in the asset properties, it refers to the timestamps valid for the actual data linked to the Asset Object. If it comes from the Item properties, it’s referencing to the timestamp valid for the metadata.

Returns:datetime
get_unpublished(asset=None)[source]

Get an Item or Asset unpublished datetime

If an Asset is supplied and the unpublished property exists on the Asset, return the Asset’s value. Otherwise return the Item’s value. ‘Unpublished’ has a different meaning depending on where it is used. If available in the asset properties, it refers to the timestamps valid for the actual data linked to the Asset Object. If it comes from the Item properties, it’s referencing to the timestamp valid for the metadata.

Returns:datetime
published
Get or sets a datetime objects that represent
the date and time that the corresponding data was published the first time.
Returns:datetime
set_expires(expires, asset=None)[source]

Set an Item or asset expires datetime

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_published(published, asset=None)[source]

Set an Item or asset published datetime

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_unpublished(unpublished, asset=None)[source]

Set an Item or asset unpublished datetime

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

unpublished

Get or sets a datetime objects that represent the Date and time the corresponding data was unpublished.

Returns:datetime

SAR Extension

Implements the SAR Extension.

SarItemExt

class pystac.extensions.sar.SarItemExt(an_item: pystac.item.Item)[source]

Bases: pystac.extensions.base.ItemExtension

SarItemExt extends Item to add sar properties to a STAC Item.

Parameters:item (Item) – The item to be extended.
item

The item that is being extended.

Type:Item

Note

Using SarItemExt to directly wrap an item will add the ‘sar’ extension ID to the item’s stac_extensions.

apply(instrument_mode: str, frequency_band: pystac.extensions.sar.FrequencyBand, polarizations: List[pystac.extensions.sar.Polarization], product_type: str, center_frequency: Optional[float] = None, resolution_range: Optional[float] = None, resolution_azimuth: Optional[float] = None, pixel_spacing_range: Optional[float] = None, pixel_spacing_azimuth: Optional[float] = None, looks_range: Optional[int] = None, looks_azimuth: Optional[int] = None, looks_equivalent_number: Optional[float] = None, observation_direction: Optional[pystac.extensions.sar.ObservationDirection] = None)[source]

Applies sar extension properties to the extended Item.

Parameters:
  • instrument_mode (str) – The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, WV for “Wave mode.”
  • frequency_band (FrequencyBand) – The common name for the frequency band to make it easier to search for bands across instruments. See section “Common Frequency Band Names” for a list of accepted names.
  • polarizations (List[Polarization]) – Any combination of polarizations.
  • product_type (str) – The product type, for example SSC, MGD, or SGC.
  • center_frequency (float) – Optional center frequency of the instrument in gigahertz (GHz).
  • resolution_range (float) – Optional range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m).
  • resolution_azimuth (float) – Optional azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m).
  • pixel_spacing_range (float) – Optional range pixel spacing, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type GRD.
  • pixel_spacing_azimuth (float) – Optional azimuth pixel spacing, which is the distance between adjacent pixels parallel to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type GRD.
  • looks_range (int) – Optional number of groups of signal samples (looks) perpendicular to the flight path.
  • looks_azimuth (int) – Optional number of groups of signal samples (looks) parallel to the flight path.
  • looks_equivalent_number (float) – Optional equivalent number of looks (ENL).
  • observation_direction (ObservationDirection) – Optional Antenna pointing direction relative to the flight trajectory of the satellite.
center_frequency

Get or sets a center frequency for the item.

Returns:float
frequency_band

Get or sets a FrequencyBand for the item.

Returns:FrequencyBand
classmethod from_item(an_item: pystac.item.Item) → SarItemExtType[source]
instrument_mode

Get or sets an instrument mode string for the item.

Returns:str
looks_azimuth

Get or sets a looks azimuth for the item.

Returns:int
looks_equivalent_number

Get or sets a looks equivalent number for the item.

Returns:float
looks_range

Get or sets a looks range for the item.

Returns:int
observation_direction

Get or sets an observation direction for the item.

Returns:ObservationDirection
pixel_spacing_azimuth

Get or sets a pixel spacing azimuth for the item.

Returns:float
pixel_spacing_range

Get or sets a pixel spacing range for the item.

Returns:float
polarizations

Get or sets a list of polarizations for the item.

Returns:List[Polarization]
product_type

Get or sets a product type string for the item.

Returns:str
resolution_azimuth

Get or sets a resolution azimuth for the item.

Returns:float
resolution_range

Get or sets a resolution range for the item.

Returns:float

SAT Extension

Implements the SAT Extension.

SatItemExt

Single File STAC Extension

These classes are representations of the Single File STAC Extension.

pystac.extensions.single_file_stac.create_single_file_stac(catalog)[source]

Creates a Single File STAC from a STAC catalog.

This method will recursively collect any collections and items in the catalog and return a new catalog with the same properties as the old one, with cleared links and the ‘collections’ and ‘features’ property of the Single File STAC holding each of the respective collected STAC objects.

Collections will be filtered to only those referenced by items via the collection_id. All links in the items and collections will be cleared in the Single File STAC.

Parameters:catalog (Catalog) – Catalog to walk while constructin the Single File STAC

SingleFileSTACCatalogExt

class pystac.extensions.single_file_stac.SingleFileSTACCatalogExt(catalog)[source]

An extension of Catalog that provides a set of Collections and Items as a single file catalog. A SingleFileSTAC is a self contained catalog that contains everything that would normally be in a linked set of STAC files.

Parameters:catalog (Catalog) – The catalog to be extended.
catalog

The catalog that is being extended.

Type:Catalog

Note

Using SingleFileSTACCatalogExt to directly wrap a Catalog will add the ‘proj’ extension ID to the catalog’s stac_extensions.

apply(features, collections=None)[source]
Parameters:
  • features (List[Item]) – List of items contained by this SingleFileSTAC.
  • collections (List[Collection]) – Optional list of collections that are used by any of the Items in the catalog.
collections

Get or sets a list of Collection objects contained in this Single File STAC.

Returns:List[Band]
classmethod enable_extension(catalog)[source]

Enables the extension for the given stac_object. Child classes can choose to override this method in order to modify the stac_object when an extension is enabled.

features

Get or sets a list of Item contained in this Single File STAC.

Returns:List[Item]
classmethod from_catalog(catalog)[source]

Version Extension

Implements the Version Extension.

VersionCollectionExt

class pystac.extensions.version.VersionCollectionExt(a_collection)[source]

Bases: pystac.extensions.base.CollectionExtension

VersionCollectionExt extends Collection to add version and deprecated properties along with links to the latest, predecessor, and successor Collections.

Parameters:a_collection (Collection) – The collection to be extended.
collection

The collection that is being extended.

Type:Collection

Note

Using VersionCollectionExt to directly wrap a collection will add the ‘version’ extension ID to the collections’s stac_extensions.

apply(version: str, deprecated: Optional[str] = None, latest: Optional[pystac.collection.Collection] = None, predecessor=None, successor=None) → None[source]

Applies version extension properties to the extended Collection.

Parameters:
  • version (str) – The version string for the collection.
  • deprecated (bool) – Optional flag set to True if an Collection is deprecated with the potential to be removed. Defaults to false if not present.
  • latest (Collection) – Collection with the latest (e.g., current) version.
  • predecessor (Collection) – Collection with the previous version.
  • successor (Collection) – Collection with the next most recent version.
deprecated

Get or sets is the collection is deprecated.

Returns:bool
classmethod from_collection(a_collection: pystac.collection.Collection)[source]
latest

Get or sets the most recent collection.

Returns:Collection or None
predecessor

Get or sets the previous collection.

Returns:Collection or None
successor

Get or sets the next collection.

Returns:Collection or None
version

Get or sets a version string of the collection.

Returns:str

VersionItemExt

class pystac.extensions.version.VersionItemExt(an_item)[source]

Bases: pystac.extensions.base.ItemExtension

VersionItemExt extends Item to add version and deprecated properties along with links to the latest, predecessor, and successor Items.

Parameters:item (Item) – The item to be extended.
item

The item that is being extended.

Type:Item

Note

Using VersionItemExt to directly wrap an item will add the ‘version’ extension ID to the item’s stac_extensions.

apply(version: str, deprecated: Optional[bool] = None, latest: Optional[pystac.item.Item] = None, predecessor: Optional[pystac.item.Item] = None, successor: Optional[pystac.item.Item] = None) → None[source]

Applies version extension properties to the extended Item.

Parameters:
  • version (str) – The version string for the item.
  • deprecated (bool) – Optional flag set to True if an Item is deprecated with the potential to be removed. Defaults to false if not present.
  • latest (Item) – Item with the latest (e.g., current) version.
  • predecessor (Item) – Item with the previous version.
  • successor (Item) – Item with the next most recent version.
deprecated

Get or sets is the item is deprecated.

Returns:bool
classmethod from_item(an_item: pystac.item.Item)[source]
latest

Get or sets the most recent item.

Returns:Item or None
predecessor

Get or sets the previous item.

Returns:Item or None
successor

Get or sets the next item.

Returns:Item or None
version

Get or sets a version string of the item.

Returns:str

View Geometry Extension

Implements the View Geometry Extension.

ViewItemExt

class pystac.extensions.view.ViewItemExt(item)[source]

Bases: pystac.extensions.base.ItemExtension

ViewItemExt is the extension of the Item in the View Geometry Extension. View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data. It will often be combined with other extensions that describe the actual data, such as the eo, sat or sar extensions.

Parameters:item (Item) – The item to be extended.
item

The Item that is being extended.

Type:Item

Note

Using ViewItemExt to directly wrap an item will add the ‘view’ extension ID to the item’s stac_extensions.

apply(off_nadir: Optional[float] = None, incidence_angle: Optional[float] = None, azimuth: Optional[float] = None, sun_azimuth: Optional[float] = None, sun_elevation: Optional[float] = None)[source]

Applies View Geometry extension properties to the extended Item.

Parameters:
  • off_nadir (float) – The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90).
  • incidence_angle (float) – The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90).
  • azimuth (float) – Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360).
  • sun_azimuth (float) – Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360).
  • sun_elevation (float) – Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90).
azimuth

Get or sets the viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360).

Returns:float
classmethod from_item(item)[source]
get_azimuth(asset=None)[source]

Gets an Item or an Asset azimuth.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
get_incidence_angle(asset=None)[source]

Gets an Item or an Asset incidence_angle.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
get_off_nadir(asset=None)[source]

Gets an Item or an Asset off_nadir.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
get_sun_azimuth(asset=None)[source]

Gets an Item or an Asset sun_azimuth.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
get_sun_elevation(asset=None)[source]

Gets an Item or an Asset sun_elevation.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value

Returns:float
incidence_angle

Get or sets the incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90).

Returns:float
off_nadir

Get or sets the angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90).

Returns:float
set_azimuth(azimuth, asset=None)[source]

Set an Item or an Asset azimuth.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_incidence_angle(incidence_angle, asset=None)[source]

Set an Item or an Asset incidence_angle.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_off_nadir(off_nadir, asset=None)[source]

Set an Item or an Asset off_nadir.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_sun_azimuth(sun_azimuth, asset=None)[source]

Set an Item or an Asset sun_azimuth.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_sun_elevation(sun_elevation, asset=None)[source]

Set an Item or an Asset sun_elevation.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

sun_azimuth

Get or sets the sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360).

Returns:float
sun_elevation

Get or sets the sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90).

Returns:float

Serialization

PySTAC includes a pystac.serialization package for serialization concerns that are used internally, but may also be useful to external tools.

Identification

pystac.serialization.identify_stac_object(json_dict)[source]

Determines the STACJSONDescription of the provided JSON dict.

Parameters:json_dict (dict) – The dict of STAC JSON to identify.
Returns:The description of the STAC object serialized in the given dict.
Return type:STACJSONDescription
class pystac.serialization.STACJSONDescription(object_type, version_range, common_extensions, custom_extensions)[source]

Describes the STAC object information for a STAC object represented in JSON

object_type

Describes the STAC object type. One of STACObjectType.

Type:str
version_range

The STAC version range that describes what has been identified as potential valid versions of the stac object.

Type:STACVersionRange
common_extensions

List of common extension IDs implemented by this STAC object.

Type:List[str]
custom_extensions

List of custom extensions (URIs to JSON Schemas) used by this STAC Object.

Type:List[str]
class pystac.serialization.STACVersionRange(min_version='0.4.0', max_version=None)[source]

Defines a range of STAC versions.

contains(v)[source]
is_earlier_than(v)[source]
is_later_than(v)[source]
is_single_version()[source]
latest_valid_version()[source]
set_max(v)[source]
set_min(v)[source]
set_to_single(v)[source]
class pystac.serialization.STACVersionID(version_string)[source]

Defines STAC versions in an object that is orderable based on version number. For instance, 1.0.0-beta.2 < 1.0.0

Migration

pystac.serialization.migrate.migrate_to_latest(json_dict, info)[source]

Migrates the STAC JSON to the latest version

Parameters:
  • json_dict (dict) – The dict of STAC JSON to identify.
  • info (STACJSONDescription) – The info from identify_stac_object() that describes the STAC object contained in the JSON dict.
Returns:

A copy of the dict that is migrated to the latest version (the version that is pystac.version.STACVersion.DEFAULT_STAC_VERSION)

Return type:

dict

Common Properties

pystac.serialization.merge_common_properties(item_dict, collection_cache=None, json_href=None)[source]

Merges Collection properties into an Item.

Parameters:
  • item_dict (dict) – JSON dict of the Item which properties should be merged into.
  • collection_cache (CollectionCache) – Optional CollectionCache that will be used to read and write cached collections.
  • json_href – The HREF of the file that this JSON comes from. Used to resolve relative paths.
Returns:

True if Collection properties have been merged, otherwise False.

Return type:

bool

Validation

pystac.validation

PySTAC includes a pystac.validation package for validating STAC objects, including from PySTAC objects and directly from JSON.

pystac.validation.validate(stac_object)[source]

Validates a STACObject.

Parameters:stac_object (STACObject) – The stac object to validate.
Returns:
List of return values from the validation calls for the
core object and any extensions. Element type is specific to the STACValidator implementation.
Return type:List[Object]
Raises:STACValidationError
pystac.validation.validate_dict(stac_dict, stac_object_type=None, stac_version=None, extensions=None, href=None)[source]

Validate a stac object serialized as JSON into a dict.

This method delegates to the call to pystac.validation.STACValidator.validate() for the STACValidator registered via set_validator() or JsonSchemaSTACValidator by default.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • stac_object_type (str) – The stac object type of the object encoded in stac_dict. One of STACObjectType. If not supplied, this will use PySTAC’s identification logic to identify the object type.
  • stac_version (str) – The version of STAC to validate the object against. If not supplied, this will use PySTAC’s identification logic to identify the stac version
  • extensions (List[str]) – Extension IDs for this stac object. If not supplied, PySTAC’s identification logic to identify the extensions.
  • href (str) – Optional HREF of the STAC object being validated.
Returns:

List of return values from the validation calls for the

core object and any extensions. Element type is specific to the STACValidator implementation.

Return type:

List[Object]

Raises:

STACValidationError

pystac.validation.validate_all(stac_dict, href)[source]

Validate STAC JSON and all contained catalogs, collections and items.

If this stac_dict represents a catalog or collection, this method will recursively be called for each child link and all contained items.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • href (str) – HREF of the STAC object being validated. Used for error reporting and resolving relative links.
Raises:

STACValidationError – This will raise a STACValidationError if this or any contained catalog, collection or item has a validation error.

pystac.validation.set_validator(validator)[source]

Sets the STACValidator to use in PySTAC.

TKTK

Parameters:validator (STACValidator) – The STACVlidator implementation to use for validation.
exception pystac.validation.STACValidationError(message, source=None)[source]

Represents a validation error. Thrown by validation calls if the STAC JSON is invalid.

Parameters:source (object) – Source of the exception. Type will be determined by the validation implementation. For the default JsonSchemaValidator this will a the jsonschema.ValidationError.

STACValidator

class pystac.validation.STACValidator[source]

STACValidator defines methods for validating STAC JSON. Implementations define methods for validating core objects and extension. By default the JsonSchemaSTACValidator is used by PySTAC; users can define their own STACValidator implementation and set that validator to be used by pystac by using the set_validator() method.

validate(stac_dict, stac_object_type, stac_version, extensions, href=None)[source]

Validate a STAC object JSON.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • stac_object_type (str) – The stac object type of the object encoded in stac_dict. One of STACObjectType.
  • stac_version (str) – The version of STAC to validate the object against.
  • extensions (List[str]) – Extension IDs for this stac object.
  • href (str) – Optional href of the STAC object being validated.
Returns:

List of return values from the validation calls for the

core object and any extensions. Element type is specific to the STACValidator implementation.

Return type:

List[Object]

validate_core(stac_dict, stac_object_type, stac_version, href=None)[source]

Validate a core stac object.

Return value can be None or specific to the implementation.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • stac_object_type (str) – The stac object type of the object encoded in stac_dict. One of STACObjectType.
  • stac_version (str) – The version of STAC to validate the object against.
  • href (str) – Optional HREF of the STAC object being validated.
validate_extension(stac_dict, stac_object_type, stac_version, extension_id, href=None)[source]

Validate an extension stac object.

Return value can be None or specific to the implementation.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • stac_object_type (str) – The stac object type of the object encoded in stac_dict. One of STACObjectType.
  • stac_version (str) – The version of STAC to validate the object against.
  • extension_id (str) – The extension ID of the extension to validate against.
  • href (str) – Optional HREF of the STAC object being validated.
class pystac.validation.JsonSchemaSTACValidator(schema_uri_map=None)[source]

Validate STAC based on JSON Schemas.

This validator uses JSON schemas, read from URIs provided by a SchemaUriMap, to validate STAC core objects and extensions.

Parameters:schema_uri_map (SchemaUriMap) – The SchemaUriMap that defines where the validator will retrieve the JSON schemas for validation. Defaults to an instance of DefaultSchemaUriMap

Note: This class requires the jsonschema library to be installed.

validate_core(stac_dict, stac_object_type, stac_version, href=None)[source]

Validate a core stac object.

Return value can be None or specific to the implementation.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • stac_object_type (str) – The stac object type of the object encoded in stac_dict. One of STACObjectType.
  • stac_version (str) – The version of STAC to validate the object against.
  • href (str) – Optional HREF of the STAC object being validated.
Returns:

URI for the JSON schema that was validated against, or None if

no validation occurred.

Return type:

str

validate_extension(stac_dict, stac_object_type, stac_version, extension_id, href=None)[source]

Validate an extension stac object.

Return value can be None or specific to the implementation.

Parameters:
  • stac_dict (dict) – Dictionary that is the STAC json of the object.
  • stac_object_type (str) – The stac object type of the object encoded in stac_dict. One of STACObjectType.
  • stac_version (str) – The version of STAC to validate the object against.
  • extension_id (str) – The extension ID to validate against.
  • href (str) – Optional HREF of the STAC object being validated.
Returns:

URI for the JSON schema that was validated against, or None if

no validation occurred.

Return type:

str

SchemaUriMap

A SchemaMapUri defines methods for mapping STAC versions, object types and extension ids to schema URIs. A default implementation is included that uses known locations; however users can provide their own schema URI maps in a JsonSchemaSTACValidator to modify the URIs used.

class pystac.validation.SchemaUriMap[source]

Abstract class defining schema URIs for STAC core objects and extensions.

get_core_schema_uri(object_type, stac_version)[source]

Get the schema URI for the given object type and stac version.

Parameters:
  • object_type (str) – STAC object type. One of STACObjectType
  • stac_version (str) – The STAC version of the schema to return.
Returns:

The URI of the schema, or None if not found.

Return type:

str

get_extension_schema_uri(extension_id, object_type, stac_version)[source]

Get the extension’s schema URI for the given object type, stac version.

Parameters:
  • extension_id (str) – The Extension ID of the extension of the schema.
  • object_type (str) – STAC object type. One of STACObjectType
  • stac_version (str) – The STAC version of the schema to return.
Returns:

The URI of the schema, or None if not found.

Return type:

str

class pystac.validation.schema_uri_map.DefaultSchemaUriMap[source]

Implementation of SchemaUriMap that uses schemas hosted by https://schemas.stacspec.org.

For STAC Versions 0.9.0 or earlier this will use the schemas hosted on the radiantearth/stac-spec GitHub repo.

get_core_schema_uri(object_type, stac_version)[source]

Get the schema URI for the given object type and stac version.

Parameters:
  • object_type (str) – STAC object type. One of STACObjectType
  • stac_version (str) – The STAC version of the schema to return.
Returns:

The URI of the schema, or None if not found.

Return type:

str

get_extension_schema_uri(extension_id, object_type, stac_version)[source]

Get the extension’s schema URI for the given object type, stac version.

Parameters:
  • extension_id (str) – The Extension ID of the extension of the schema.
  • object_type (str) – STAC object type. One of STACObjectType
  • stac_version (str) – The STAC version of the schema to return.
Returns:

The URI of the schema, or None if not found.

Return type:

str

PySTAC Internal Classes

ResolvedObjectCache

class pystac.cache.ResolvedObjectCache(id_keys_to_objects=None, hrefs_to_objects=None, ids_to_collections=None)[source]

This class tracks resolved objects tied to root catalogs. A STAC object is ‘resolved’ when it is a Python Object; a link to a STAC object such as a Catalog or Item is considered “unresolved” if it’s target is pointed at an HREF of the object.

Tracking resolved objects allows us to tie together the same instances when there are loops in the Graph of the STAC catalog (e.g. a LabelItem can link to a rel:source, and if that STAC Item exists in the same root catalog they should refer to the same Python object).

Resolution tracking is important when copying STACs in-memory: In order for object links to refer to the copy of STAC Objects rather than their originals, we have to keep track of the resolved STAC Objects and replace them with their copies.

Parameters:
  • id_keys_to_objects (Dict[str, STACObject]) – Existing cache of a key made up of the STACObject and it’s parents IDs mapped to the cached STACObject.
  • hrefs_to_objects (Dict[str, STACObject]) – STAC Object HREFs matched to their cached object.
  • ids_to_collections (Dict[str, Collection]) – Map of collection IDs to collections.
as_collection_cache()[source]
cache(obj)[source]

Set the given object into the cache.

Parameters:obj (STACObject) – The object to cache
contains_collection_id(collection_id)[source]

Returns True if there is a collection with given collection ID is cached.

get(obj)[source]

Get the cached object that has the same cache key as the given object.

Parameters:obj (STACObject) – The given object who’s cache key will be checked against the cache.
Returns:Either the cached object that has the same cache key as the given object, or None
Return type:STACObject or None
get_by_href(href)[source]

Gets the cached object at href.

Parameters:href (str) – The href to use as the key for the cached object.
Returns:Returns the STACObject if cached, otherwise None.
Return type:STACObject or None
get_collection_by_id(id)[source]

Retrieved a cached Collection by its ID.

Parameters:id (str) – The ID of the collection.
Returns:
Returns the collection if there is one cached
with the given ID, otherwise None.
Return type:Collection or None
get_or_cache(obj)[source]

Gets the STACObject that is the cached version of the given STACObject; or, if none exists, sets the cached object to the given object.

Parameters:obj (STACObject) – The given object who’s cache key will be checked against the cache.
Returns:Either the cached object that has the same cache key as the given object, or the given object.
Return type:STACObject
static merge(first, second)[source]

Merges two ResolvedObjectCache.

The merged cache will give preference to the first argument; that is, if there are cached keys that exist in both the first and second cache, the object cached in the first will be cached in the resulting merged ResolvedObjectCache.

Parameters:
  • first (ResolvedObjectCache) – The first cache to merge. This cache will be the preferred cache for objects in the case of ID conflicts.
  • second (ResolvedObjectCache) – The second cache to merge.
Returns:

The resulting merged cache.

Return type:

ResolvedObjectCache

remove(obj)[source]

Removes any cached object that matches the given object’s cache key.

Parameters:obj (STACObject) – The object to remove