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)

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)

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 functinoality 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.

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

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.

links

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

Type:List[Link]

add_link(link)

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

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

add_links(links)

Add links to this object’s set of links.

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

clear_links(rel=None)

Clears all Link instances associated with this object.

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

clone()

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)

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)

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)

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

fully_resolve()

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.

get_links(rel=None)

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()

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()

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_root_link()

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(rel)

Get single link that match the given rel.

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

get_stac_objects(rel)

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]

make_links_absolute()

Sets each link associated with this object to be absolute. See Link.make_absolute for more information.

make_links_relative()

Sets each link associated with this object to be relative. This does not include the self link, as those must always be absolute. See Link.make_relative for more information.

normalize_hrefs(root_href)

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.

See:

STAC best practices document for the canonical layout of a STAC.

remove_links(rel)

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

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

save_object(include_self_link=True, dest_href=None)

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, link_type=None)

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.
• link_type (str) – The link type (see LinkType)

set_root(root, link_type=None)

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.
• link_type (str) – The link type (see LinkType)

set_self_href(href)

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

Parameters: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.

to_dict(include_self_link=True)

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

Catalog Spec

These classes are representations of the Catalog Spec.

Catalog

class pystac.Catalog(id, description, title=None, stac_extensions=None, href=None)

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.

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

links

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

Type:List[Link]

DEFAULT_FILE_NAME = 'catalog.json'

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

add_child(child, title=None)

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:

• child (Catalog or Collection) – The child to add.
• title (str) – Optional title to give to the Link

add_item(item, title=None)

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)

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()

Removes all children from this catalog.

Returns:Returns self Return type:Catalog

clear_items()

Removes all items from this catalog.

Returns:Returns self Return type:Catalog

clone()

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)

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)

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

fully_resolve()

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.

get_all_items()

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)

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

get_child_links()

Return all child links of this catalog.

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

get_children()

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)

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

get_item_links()

Return all item links of this catalog.

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

get_items()

Return all items of this catalog.

Returns:Generator of items who’s parent is this catalog. Return type:Generator[Item]

make_all_asset_hrefs_absolute()

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

make_all_asset_hrefs_relative()

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

make_all_links_absolute()

Makes all the links of this catalog and all children and item to be absolute, recursively

make_all_links_relative()

Makes all the links of this catalog and all children and item to be relative, recursively

map_assets(asset_mapper)

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 safetly. Returns:A full copy of this catalog, with assets manipulated according to the asset_mapper function. Return type:Catalog

map_items(item_mapper)

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 safetly. 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)

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

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.

normalize_hrefs(root_href)

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.

See:

STAC best practices document for the canonical layout of a STAC.

remove_child(child_id)

Removes an child from this catalog.

Parameters:child_id (str) – The ID of the child to remove.

remove_item(item_id)

Removes an item from this catalog.

Parameters:item_id (str) – The ID of the item to remove.

save(catalog_type)

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.

Note

If the catalog type is CatalogType.ABSOLUTE_PUBLISHED, all self links will be included, and link type will be set to ABSOLUTE. If the catalog type is CatalogType.RELATIVE_PUBLISHED, this catalog’s self link will be included, but no child catalog will have self links. Link types will be set to RELATIVE. If the catalog type is CatalogType.SELF_CONTAINED, no self links will be included. Link types will be set to RELATIVE.

set_root(root, link_type='ABSOLUTE')

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.
• link_type (str) – The link type (see LinkType)

to_dict(include_self_link=True)

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

walk()

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

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, license='proprietary', keywords=None, providers=None, properties=None, summaries=None)

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.
• 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.

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

links

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

Type:List[Link]

DEFAULT_FILE_NAME = 'collection.json'

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

add_item(item, title=None)

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()

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)

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

set_self_href(href)

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

Parameters: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.

Note

Overridden for collections so that the root’s ResolutionObjectCache can properly update the HREF cache.

to_dict(include_self_link=True)

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

Extent

class pystac.Extent(spatial, temporal)

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()

Clones this object.

Returns:The clone of this extent. Return type:Extent

static from_dict(d)

Constructs an Extent from a dict.

Returns:The Extent deserialized from the JSON dict. Return type:Extent

to_dict()

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)

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()

Clones this object.

Returns:The clone of this object. Return type:SpatialExtent

static from_coordinates(coordinates)

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)

Constructs an SpatialExtent from a dict.

Returns:The SpatialExtent deserialized from the JSON dict. Return type:SpatialExtent

to_dict()

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)

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()

Clones this object.

Returns:The clone of this object. Return type:TemporalExtent

static from_dict(d)

Constructs an TemporalExtent from a dict.

Returns:The TemporalExtent deserialized from the JSON dict. Return type:TemporalExtent

static from_now()

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()

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)

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)

Constructs an Provider from a dict.

Returns:The Provider deserialized from the JSON dict. Return type:TemporalExtent

to_dict()

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)

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]) – 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.
• datetime (datetime) – Datetime associated with this item.
• 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.

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.

Type:List[float]

datetime

Datetime associated with this item.

Type:datetime

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

links

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

add_asset(key, asset)

Adds an Asset to this item.

Parameters:

• key (str) – The unique key of this asset.
• asset (Asset) – The Asset to add.

clone()

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)

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

fully_resolve()

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.

get_assets()

Get this item’s assets.

Returns:A copy of the dictonary of this item’s assets. Return type:Dict[str, Asset]

make_asset_hrefs_absolute()

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()

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

Returns:self Return type:Item

normalize_hrefs(root_href)

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.

See:

STAC best practices document for the canonical layout of a STAC.

set_collection(collection, link_type=None)

Set the collection of this item.

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

Parameters:

• collection (Collection) – The collection to set as this item’s collection.
• link_type (str) – the link type to use for the collection link. One of LinkType.

Returns:

self

Return type:

Item

to_dict(include_self_link=True)

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)

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()

Clones this asset.

Returns:The clone of this asset. Return type:Asset

static from_dict(d)

Constructs an Asset from a dict.

Returns:The Asset deserialized from the JSON dict. Return type:Asset

get_absolute_href()

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)

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()

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)

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 to search for common common metadata fields in

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

instruments

Get or set the names of the instruments used

Returns:Name(s) of instrument(s) used Return type:[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:[Provider]

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 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:

Date and time that the metadata file was most recently

updated

Return type:datetime

ItemCollection

class pystac.ItemCollection(features=None, stac_extensions=None)

A GeoJSON FeatureCollection that is augmented with foreign members relevant to a STAC entity.

Parameters:

• features (List[Item]) – Optional initial list of items contained by this ItemCollection.
• stac_extensions (List[str]) – Optional list of extensions implemented.

features

Items contained by this ItemCollection

Type:List[Item]

links

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

Type:List[Link]

add_item(item)

Adds an Item to this ItemCollection.

Parameters:item (Item) – The item to add.

add_items(items)

Adds Items to this ItemCollection.

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

static from_dict(d)

Constructs an ItemCollection from a dict.

Returns:The ItemCollection deserialized from the JSON dict. Return type:ItemCollection

static from_file(href)

Reads an ItemCollection from a file.

Parameters:href (str) – The HREF to read the item from. Returns:ItemCollection that was read from the given file. Return type:ItemCollection

get_items()

Gets all the items associated with this ItemCollection.

Returns:The Items of this ItemCollection Return type:List[Item]

save(href=None, include_self_link=True)

Saves this ItemCollection.

Parameters:

• href (str) – The HREF to save the ItemCollection to. If None, will save to the currently set self link. If supplied, will set this href to the ItemCollection’s self link.
• include_self_link (bool) – If True, will include the self link in the set of links of the saved JSON.

to_dict(include_self_link=False)

Generate a dictionary representing the JSON of this ItemCollection.

Parameters:include_self_link (bool) – If True, writes the ItemCollection’s self link. Defaults to False. Returns:A serializion of the ItemCollection that can be written out as JSON. Return type:dict

Links

Catalogs, Collections and Items have links, which allow users to crawl catalogs.

Link

class pystac.Link(rel, target, media_type=None, title=None, properties=None, link_type='ABSOLUTE')

A link is connects a STACObject to another entity.

The target of a link can be either another STACObject, or an HREF. When serialized, links always refer to the HREF of the target. Links are lazily deserialized - this is, when you read in a link, it does not automatically load in the STACObject that is the target (if the link is pointing to a STACObject). When a user is crawling through a catalog or when additional metadata is required, PySTAC uses the Link.resolve_stac_object method to load in and deserialize STACObjects. This mechanism is used within the PySTAC codebase and normally does not need to be considered by the user - ideally the lazy deserialization of STACObjects is transparent to clients of PySTAC.

Parameters:

• rel (str) – The relation of the link (e.g. ‘child’, ‘item’)
• target (str or STACObject) – The target of the link. If the link is unresolved, or the link is to something that is not a STACObject, the target is an HREF. If resolved, the target is a STACObject.
• media_type (str) – Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.
• title (str) – Optional title for this link.
• properties (dict) – Optional, additional properties for this link. This is used by extensions as a way to serialize and deserialize properties on link object JSON.
• link_type (str) – The link type, either relative or absolute. Use one of LinkType.

rel

The relation of the link (e.g. ‘child’, ‘item’)

Type:str

target

The target of the link. If the link is unresolved, or the link is to something that is not a STACObject, the target is an HREF. If resolved, the target is a STACObject.

Type:str or STACObject

media_type

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

Type:str or None

title

Optional title for this link.

Type:str or None

properties

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

Type:dict or None

link_type

The link type, either relative or absolute. Use one of LinkType.

Type:str

owner

The owner of this link. The link will use its owner’s root catalog ResolvedObjectCache to resolve objects, and will create absolute HREFs from relative HREFs against the owner’s self HREF.

Type:STACObject or None

static child(c, title=None, link_type='ABSOLUTE')

Creates a link to a child Catalog or Collection.

clone()

Clones this link.

This makes a copy of all link information, but does not clone a STACObject if one is the target of this link.

Returns:The cloned link. Return type:Link

static collection(c, link_type='ABSOLUTE')

Creates a link to an item’s Collection.

static from_dict(d)

Deserializes a Link from a dict.

Parameters:d (dict) – The dict that represents the Link in JSON Returns:Link instance constructed from the dict. Return type:Link

get_absolute_href()

Gets the aboslute href for this link, if possible.

Returns:Returns this link’s HREF. It attempts to derive an absolute HREF from this link; however, if the link is relative, has no owner, and has an unresolved target, this will return a relative HREF. Return type:str

get_href()

Gets the HREF for this link.

Returns:Returns this link’s HREF. If the link type is LinkType.RELATIVE, and there is an owner of the link, then the HREF returned will be relative. In all other cases, this method will return an absolute HREF. Return type:str

is_resolved()

Determines if the link’s target is a resolved STACObject.

Returns:True if this link is resolved. Return type:bool

static item(item, title=None, link_type='ABSOLUTE')

Creates a link to an Item.

make_absolute()

Sets the link type of this link to absolute

make_relative()

Sets the link type of this link to relative

static parent(c, link_type='ABSOLUTE')

Creates a link to a parent Catalog or Collection.

resolve_stac_object(root=None)

Resolves a STAC object from the HREF of this link, if the link is not already resolved.

Parameters:root (Catalog or Collection) – Optional root of the catalog for this link. If provided, the root’s resolved object cache is used to search for previously resolved instances of the STAC object.

static root(c, link_type='ABSOLUTE')

Creates a link to a root Catalog or Collection.

static self_href(href)

Creates a self link to a file’s location.

set_owner(owner)

Sets the owner of this link.

Parameters:owner (STACObject) – The owner of this link.

to_dict()

Generate a dictionary representing the JSON of this serialized Link.

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

LinkType

class pystac.LinkType

Enumerates link types; used to determine if a link is absolute or relative.

ABSOLUTE = 'ABSOLUTE'

RELATIVE = 'RELATIVE'

MediaType

class pystac.MediaType

A list of common media types that can be used in STAC Asset and Link metadata.

COG = 'image/tiff; application=geotiff; profile=cloud-optimized'

GEOJSON = 'application/geo+json'

GEOPACKAGE = 'application/geopackage+sqlite3'

GEOTIFF = 'image/tiff; application=geotiff'

HDF = 'application/x-hdf'

HDF5 = 'application/x-hdf5'

JPEG = 'image/jpeg'

JPEG2000 = 'image/jp2'

JSON = 'application/json'

PNG = 'image/png'

TEXT = 'text/plain'

TIFF = 'image/tiff'

XML = 'application/xml'

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

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()

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

default_write_text_method(txt)

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

classmethod read_json(uri)

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)

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)

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)

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)

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.

Errors

STACError

class pystac.STACError

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

An error related to the construction of extensions.

Extensions

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)

__getattr__(extension_id)

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)

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)

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)

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)

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(gsd, bands, cloud_cover=None)

Applies label extension properties to the extended Item.

Parameters:

• gsd (float) – The Ground Sample Distance of the sensor
• 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)

get_asset_bands(asset)

Gets the bands for the given asset.

Parameters:[Asset] (asset) – The asset from the associated item to get the bands of. Returns:A list of Band objects associated with the asset, or None if the asset doesn’t exist or does not contain band information. Return type:[List[Band] or None]

gsd

Get or sets the Ground Sample Distance at the sensor.

Returns:[float]

set_asset_bands(asset, band_names)

Sets the band information for an asset of this item.

Parameters:

• [Asset] (asset) – The asset from the associated item to set the bands for.
• band_names (List[str]) – List of band names to assign to the asset. These names must reference names in the item’s bands property.

Band

class pystac.extensions.eo.Band(properties)

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)

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)

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)

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)

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()

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)

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)

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)

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)

Adds a link to a source item.

Parameters:

• source_item (Item) – Source imagery that the LabelItem applys to.
• title (str) – Optional title for the link.
• assets (List[str]) – Optional list of assets that deterime what assets in the source item this label item data appliees to.

apply(label_description, label_type, label_properties=None, label_classes=None, label_tasks=None, label_methods=None, label_overviews=None)

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 (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)

get_sources()

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

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)

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)

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)

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()

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)

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)

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)

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)

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()

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)

Contains counts for categorical data.

Use LabelCount.create to create a new LabelCount

apply(name, count)

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 occurences of the class.

Returns:[int]

classmethod create(name, count)

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()

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)

Contains statistics for regression/continuous numeric value data.

Use LabelStatistics.create to create a new instance.

apply(name, value)

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)

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()

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]

Single File STAC Extension

These classes are representations of the Single File STAC Extension.

SingleFileSTAC

class pystac.extensions.single_file_stac.SingleFileSTAC(features=None, stac_extensions=None, collections=None, search=None)

Provides a set of Collections and Items as a single file catalog. The single file is a self contained catalog that contains everything that would normally be in a linked set of STAC files.

Parameters:

• features (List[Item]) – Optional initial list of items contained by this SingleFileSTAC.
• stac_extensions (List[str]) – Optional list of extensions implemented.
• collections (List[Collection]) – Optional initial list of collections contained by this SingleFileSTAC.
• search (Search) – Optional search information associated with this SingleFileSTAC.

features

Items contained by this ItemCollection

Type:List[Item]

collections

Collections contained by this SingleFileSTAC.

Type:List[Collection]

search

Optional search information associated with this SingleFileSTAC.

Type:Search

links

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

Type:List[Link]

add_collection(collection)

Adds a Collection to this SingleFileSTAC.

Parameters:collection (Collection) – The collection to add.

add_collections(collections)

Adds Collections to this SingleFileSTAC.

Parameters:collections (Iterable[Collection]) – The collections to add.

static from_dict(d)

Constructs an SingleFileSTAC from a dict.

Returns:The SingleFileSTAC deserialized from the JSON dict. Return type:SingleFileSTAC

static from_file(uri)

Reads an SingleFileSTAC from a file.

Parameters:href (str) – The HREF to read the item from. Returns:SingleFileSTAC that was read from the given file. Return type:SingleFileSTAC

get_collections()

Gets all the collections associated with this SingleFileSTAC.

Returns:The Collections of this SingleFileSTAC Return type:List[Collection]

to_dict(include_self_link=False)

Generate a dictionary representing the JSON of this SingleFileSTAC.

Parameters:include_self_link (bool) – If True, writes the ItemCollection’s self link. Defaults to False. Returns:A serializion of the SingleFileSTAC that can be written out as JSON. Return type:dict

Serialization

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

merge_common_properties

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

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

indentify_stac_object

pystac.serialization.identify_stac_object(json_dict)

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

Note

Items are expected to have their collection common properties merged into the dict. You can use merge_common_properties() to accomplish that. Otherwise, there are cases where the common_extensions returned could be incorrect - e.g. if a collection lists ‘eo’ extension properties but the Item does not contian any properties with the ‘eo:’ prefix.

indentify_stac_object_type

pystac.serialization.identify_stac_object_type(json_dict)

Determines the STACObjectType of the provided JSON dict.

Parameters:json_dict (dict) – The dict of STAC JSON to identify. Returns:The object type represented by the JSON. Return type:STACObjectType

STACJSONDescription

class pystac.serialization.STACJSONDescription(object_type, version_range, common_extensions, custom_extensions)

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

object_type

Describes the STAC object type.

Type:STACObjectType

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]

STACVersionRange

class pystac.serialization.STACVersionRange(min_version='0.4.0', max_version='0.9.0')

contains(v)

is_earlier_than(v)

is_later_than(v)

is_single_version()

latest_valid_version()

set_max(v)

set_min(v)

set_to_single(v)

STACObjectType

class pystac.serialization.STACObjectType

CATALOG = 'CATALOG'

COLLECTION = 'COLLECTION'

ITEM = 'ITEM'

ITEMCOLLECTION = 'ITEMCOLLECTION'

PySTAC Internal Classes

ResolvedObjectCache

class pystac.cache.ResolvedObjectCache(ids_to_objects=None, ids_to_hrefs=None, hrefs_to_ids=None)

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:

• ids_to_objects (Dict[str, STACObject]) – Existing cache of STACObject IDs mapped
• the cached STACObject. (to) –
• ids_to_hrefs (Dict[str, str]) – Cache of STACObject IDs to their HREFs.
• hrefs_to_ids –

as_collection_cache()

cache(obj)

Set the given object into the cache.

Parameters:obj (STACObject) – The object to cache

clone()

Clone this ResolvedObjectCache

Returns:A clone of this cache, which contains a shallow copy of the ID to STACObject cache. Return type:ResolvedObjectCache

contains_id(obj_id)

get(obj)

Get the cached object that has the same ID as the given object.

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

get_by_href(href)

get_by_id(obj_id)

Get the cached object that has the given ID.

Parameters:obj_id (str) – The ID to be checked against the cache. Returns:Either the cached object that has the given ID, or None Return type:STACObject or None

get_or_cache(obj)

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 ID will be checked against the cache. Returns:Either the cached object that has the same ID as the given object, or the given object. Return type:STACObject

static merge(first, second)

Merges two ResolvedObjectCache.

The merged cache will give preference to the first argument; that is, if there are cached IDs 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 prefered 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)

Removes any cached object that matches the given object’s id.

Parameters:obj (STACObject) – The object to remove

remove_by_id(obj_id)

Removes any cached object that matches the given ID.

Parameters:obj_id (str) – The object ID to remove