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.

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.

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.

Catalog Spec

These classes are representations of the Catalog Spec.

Catalog

class pystac.Catalog(id, description, title=None, stac_extensions=None, href=None)[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.
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

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)[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_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
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
fully_resolve()[source]

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()[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]
make_all_asset_hrefs_absolute()[source]

Makes all the HREFs of assets belonging to items in this catalog and all children to be absoluet, 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.

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

Makes all the links of this catalog and all children and item 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 safetly.
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 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)[source]

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

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')[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.
  • link_type (str) – The link type (see LinkType)
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
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]
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, version=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.
  • license (str) – Collection’s license(s) as a SPDX License identifier or expression. Defaults to ‘proprietary’.
  • keywords (List[str]) – Optional list of keywords describing the collection.
  • version (str) – Optional version of 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
version

Optional version of the Collection.

Type: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]
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)[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
set_self_href(href)[source]

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

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
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)[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]) – 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

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)[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
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
fully_resolve()[source]

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()[source]

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()[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
normalize_hrefs(root_href)[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.
See:
STAC best practices document for the canonical layout of a STAC.
set_collection(collection, link_type=None)[source]

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)[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, media_type=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.
  • 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.
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
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

ItemCollection

class pystac.ItemCollection(features=None)[source]

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

Items contained by this ItemCollection

Type:List[Item]

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

Type:List[Link]
add_item(item)[source]

Adds an Item to this ItemCollection.

Parameters:item (Item) – The item to add.
add_items(items)[source]

Adds Items to this ItemCollection.

Parameters:items (Iterable[Item]) – The items to add.
static from_dict(d)[source]

Constructs an ItemCollection from a dict.

Returns:The ItemCollection deserialized from the JSON dict.
Return type:ItemCollection
static from_file(href)[source]

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()[source]

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)[source]

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)[source]

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

EO Extension

These classes are representations of the EO Extension Spec.

EOItem

class pystac.EOItem(id, geometry, bbox, datetime, properties, gsd, platform, instrument, bands, constellation=None, epsg=None, cloud_cover=None, off_nadir=None, azimuth=None, sun_azimuth=None, sun_elevation=None, stac_extensions=None, href=None, collection=None)[source]

Bases: pystac.item.Item

EOItem represents a snapshot of the earth for a single date and time.

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.
  • gsd (float) – Ground Sample Distance at the sensor.
  • platform (str) – Unique name of the specific platform to which the instrument is attached.
  • instrument (str) – Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1).
  • bands (List[Band]) – This is a list of Band objects that represent the available bands.
  • constellation (str) – Optional name of the constellation to which the platform belongs.
  • epsg (int) – Optional EPSG code.
  • cloud_cover (float) – Optional estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.
  • off_nadir (float) – Optional viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90).
  • azimuth (float) – Optional 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) – Optional 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) – Optional sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90).
  • 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
gsd

Ground Sample Distance at the sensor.

Type:float
platform

Unique name of the specific platform to which the instrument is attached.

Type:str
instrument

Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1).

Type:str
bands

This is a list of Band objects that represent the available bands.

Type:List[Band]
constellation

Name of the constellation to which the platform belongs.

Type:str or None
epsg

EPSG code.

Type:int or None
cloud_cover

Estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.

Type:float or None
off_nadir

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

Type:float or None
azimuth

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

Type:float or None
sun_azimuth

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

Type:float or None
sun_elevation

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

Type:float 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
add_asset(key, asset)[source]

Adds an Asset to this item. If this Asset contains band information in it’s properties, converts the Asset to an EOAsset.

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
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_item(item)[source]

Creates an EOItem from an Item.

Parameters:item (Item) – The Item to create an EOItem from.
Returns:
A new EOItem from item. If the item
item is already an EOItem, simply returns a clone of item.
Return type:EOItem
get_eo_assets()[source]

Gets the assets of this item that are EOAsset s.

Returns:This item’s assets, subestted to only include EOAssets.
Return type:Dict[EOAsset]
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

EOAsset

class pystac.EOAsset(href, bands, title=None, media_type=None, properties=None)[source]

Bases: pystac.item.Asset

An Asset that contains band information via a bands property that is an array of 0 based indexes to the correct band object on the owning EOItem.

Parameters:
  • href (str) – Link to the asset object. Relative and absolute links are both allowed.
  • bands (List[int]) – Lists the band names available in the asset.
  • 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.
href

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

Type:str
bands

Lists the band names available in the asset.

Type:List[int]
title

Optional displayed title for clients and users.

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
classmethod from_asset(asset)[source]

Constructs an EOAsset from an Asset.

Returns:

The EOAsset created from this asset. If the asset is already an EOAsset, will return a clone.
Return type:

EOAsset
Raises:
  • STACError – Raised if no band information is in the properties
  • of asset.
static from_dict(d)[source]

Constructs an EOAsset from a dict.

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

Returns the band information from the owning item for the bands referenced by this EOAsset.

Returns:

The band information from the owning item for each band that is represented by this EOAsset’s bands.
Return type:

List[Band]
Raises:
  • STACError – Raised if no band information is in the properties
  • of asset.
static is_eo_asset(asset)[source]

Method for checking if an Asset represents an EOAsset.

Parameters:asset (Asset) – The asset to check.
Returns:True if the asset is an instance of EOAsset, or if the asset contains eo:band information in it’s properties.
Return type:bool
to_dict()[source]

Generate a dictionary representing the JSON of this EOAsset.

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

Band

class pystac.Band(name=None, common_name=None, description=None, gsd=None, accuracy=None, center_wavelength=None, full_width_half_max=None)[source]

Represents Band information attached to an EOItem.

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.
  • gsd (float) – Ground Sample Distance, the nominal distance between pixel centers available, in meters. Defaults to the EOItems’ eo:gsd if not provided.
  • accuracy (float) – The expected error between the measured location and the true location of a pixel, in meters on the ground.
  • 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).
name

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

Type:str
common_name

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.

Type:str
description

Description to fully explain the band.

Type:str
gsd

Ground Sample Distance, the nominal distance between pixel centers available, in meters. Defaults to the EOItems’ eo:gsd if not provided.

Type:float
accuracy

The expected error between the measured location and the true location of a pixel, in meters on the ground.

Type:float
center_wavelength

The center wavelength of the band, in micrometers (μm).

Type:float
full_width_half_max

Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).

Type:float
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
static from_dict(d)[source]

Constructs a Band from a dict.

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

Generate a dictionary representing the JSON of this Band.

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

Label Extension

These classes are representations of the Label Extension Spec.

LabelItem

class pystac.LabelItem(id, geometry, bbox, datetime, properties, label_description, label_type, label_properties=None, label_classes=None, label_tasks=None, label_methods=None, label_overviews=None, stac_extensions=None, href=None, collection=None)[source]

Bases: pystac.item.Item

A Label Item represents a polygon, set of polygons, or raster data defining labels and label metadata and should be part of a Collection.

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.
  • label_desecription (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 (dict 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).
  • 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) – Optional Collection that this item is a part of.
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
label_desecription

A description of the label, how it was created, and what it is recommended for

Type:str
label_type

An ENUM of either vector label type or raster label type (one of LabelType).

Type:str
label_properties

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.

Type:dict or None
label_classes

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)

Type:List[LabelClass]
label_tasks

Tasks these labels apply to. Usually a subset of ‘regression’, ‘classification’, ‘detection’, or ‘segmentation’, but may be an arbitrary value.

Type:str
label_methods

Methods used for labeling. Usually a subset of ‘automated’ or ‘manual’, but may be an arbitrary value.

label_overviews

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

Type:List[LabelOverview]
stac_extensions

Optional list of extensions the Item implements.

Type:List[str] or None
collection_id

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

Type:str or None
See:
Item fields in the label extension spec
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 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.
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
classmethod from_item(item)[source]

Creates a LabelItem from an Item.

Parameters:item (Item) – The Item to create an LabelItem from.
Returns:
A new LabelItem from item. If the item
item is already an LabelItem, simply returns a clone of item.
Return type:LabelItem
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]
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

LabelType

class pystac.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.LabelClasses(classes, name=None)[source]
Defines the list of possible class names (e.g.,
tree, building, car, hippo)
Parameters:
  • classes (List[str]) – 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

The different possible class values

Type:List[str]
name

The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, this is None.

Type:str or None
static from_dict(d)[source]

Constructs a LabelClasses from a dict.

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

Generate a dictionary representing the JSON of this LabelClasses.

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

LabelOverview

class pystac.LabelOverview(property_key, counts=None, statistics=None)[source]

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

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.
  • statistics (List[Statistics]) – Optional list of Statistics.
Attributes
property_key (str): The property key within the asset corresponding to class labels. counts (List[LabelCounts] or None): Optional list of LabelCounts. statistics (List[Statistics] or None): Optional list of Statistics.
static from_dict(d)[source]

Constructs a LabelOverview from a dict.

Returns:The LabelOverview deserialized from the JSON dict.
Return type:LabelOverview
merge_counts(other)[source]

Merges the counts associated with this overview with another overview.

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
to_dict()[source]

Generate a dictionary representing the JSON of this LabelOverview.

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

LabelCount

class pystac.LabelCount(name, count)[source]
static from_dict(d)[source]

Constructs a LabelCount from a dict.

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

Generate a dictionary representing the JSON of this LabelCount.

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

LabelStatistics

class pystac.LabelStatistics(name, value)[source]
static from_dict(d)[source]

Constructs a LabelStatistics from a dict.

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

Generate a dictionary representing the JSON of this LabelStatistics.

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

Single File STAC Extension

These classes are representations of the Single File STAC Extension.

SingleFileSTAC

class pystac.SingleFileSTAC(features=None, collections=None, search=None)[source]

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

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

Type:List[Link]
add_collection(collection)[source]

Adds a Collection to this SingleFileSTAC.

Parameters:collection (Collection) – The collection to add.
add_collections(collections)[source]

Adds Collections to this SingleFileSTAC.

Parameters:collections (Iterable[Collection]) – The collections to add.
static from_dict(d)[source]

Constructs an SingleFileSTAC from a dict.

Returns:The SingleFileSTAC deserialized from the JSON dict.
Return type:SingleFileSTAC
static from_file(uri)[source]

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()[source]

Gets all the collections associated with this SingleFileSTAC.

Returns:The Collections of this SingleFileSTAC
Return type:List[Collection]
to_dict(include_self_link=False)[source]

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

indentify_stac_object

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

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)[source]

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)[source]

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[source]
contains(v)[source]
is_earlier_than(v)[source]
is_single_version()[source]
latest_valid_version()[source]
set_max(v)[source]
set_min(v)[source]
set_to_single(v)[source]

STACObjectType

class pystac.serialization.STACObjectType[source]
CATALOG = 'CATALOG'
COLLECTION = 'COLLECTION'
ITEM = 'ITEM'
ITEMCOLLECTION = 'ITEMCOLLECTION'

PySTAC Internal Classes

STACObject

class pystac.STACObject[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]
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
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
fully_resolve()[source]

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_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_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]
normalize_hrefs(root_href)[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.
See:
STAC best practices document for the canonical layout of a STAC.
save_object(include_self_link=True)[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.
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)[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.
  • link_type (str) – The link type (see LinkType)
set_root(root, link_type=None)[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.
  • link_type (str) – The link type (see LinkType)
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

ResolvedObjectCache