pystac.item#

class pystac.item.Item(id: str, geometry: Dict[str, Any] | None, bbox: List[float] | None, datetime: Datetime | None, properties: Dict[str, Any], start_datetime: Datetime | None = None, end_datetime: Datetime | None = None, stac_extensions: List[str] | None = None, href: str | None = None, collection: str | Collection | None = None, extra_fields: Dict[str, Any] | None = None, assets: Dict[str, Asset] | None = None)[source]

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 – Provider identifier. Must be unique within the STAC.

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

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

  • datetime – datetime associated with this item. If None, a start_datetime and end_datetime must be supplied.

  • properties – A dictionary of additional metadata for the item.

  • start_datetime – Optional start datetime, part of common metadata. This value will override any start_datetime key in properties.

  • end_datetime – Optional end datetime, part of common metadata. This value will override any end_datetime key in properties.

  • stac_extensions – Optional list of extensions the Item implements.

  • href – Optional HREF for this item, which be set as the item’s self link’s HREF.

  • collection – The Collection or Collection ID that this item belongs to.

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

  • assets – A dictionary mapping string keys to Asset objects. All Asset values in the dictionary will have their owner attribute set to the created Item.

STAC_OBJECT_TYPE: STACObjectType = 'Feature'
add_asset(key: str, asset: Asset) → None[source]

Adds an Asset to this item.

Parameters:

  • key – The unique key of this asset.

  • asset – The Asset to add.

add_derived_from(*items: Item | str) → Item[source]

Add one or more items that this is derived from.

This method will add to any existing “derived_from” links.

Parameters:

items – Items (or href of items) to add to derived_from links.

Returns:

self

Return type:

Item

assets: Dict[str, Asset]

Dictionary of Asset objects, each with a unique key.

bbox: List[float] | None

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

clone() → Item[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

collection: Collection | None

Collection to which this Item belongs, if any.

collection_id: str | None

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

property common_metadata: CommonMetadata

Access the item’s common metadata fields as a CommonMetadata object.

datetime: Datetime | None

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

delete_asset(key: str) → None[source]

Deletes the asset at the given key, and removes the asset’s data file from the local filesystem.

It is an error to attempt to delete an asset’s file if it is on a remote filesystem.

To delete the asset without removing the file, use del item.assets[“key”].

Parameters:

key – The unique key of this asset.

extra_fields: Dict[str, Any]

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

classmethod from_dict(d: Dict[str, Any], href: str | None = None, root: Catalog | None = None, migrate: bool = False, preserve_dict: bool = True) → T[source]

Parses this STACObject from the passed in dictionary.

Parameters:

  • d – The dict to parse.

  • href – Optional href that is the file location of the object being parsed.

  • root – Optional root catalog for this object. If provided, the root of the returned STACObject will be set to this parameter.

  • migrate – Use True if this dict represents JSON from an older STAC object, so that migrations are run against it.

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

Returns:

The STACObject parsed from this dict.

Return type:

STACObject

full_copy(root: Catalog | None = None, parent: Catalog | None = None) → Item[source]

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

Parameters:

  • root – Optional root to set as the root of the copied object, and any other copies that are contained by this object.

  • parent – 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

geometry: Dict[str, Any] | None

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

get_assets(media_type: str | MediaType | None = None, role: str | None = None) → Dict[str, Asset][source]

Get this item’s assets.

Parameters:

  • media_type – If set, filter the assets such that only those with a matching media_type are returned.

  • role – If set, filter the assets such that only those with a matching role are returned.

Returns:

A dictionary of assets that match media_type

and/or role if set or else all of this item’s assets.

Return type:

Dict[str, Asset]

get_collection() → Collection | None[source]

Gets the collection of this item, if one exists.

Returns:

If this item belongs to a collection, returns a reference to the collection. Otherwise returns None.

Return type:

Collection or None

get_datetime(asset: Asset | None = None) → Datetime | None[source]

Gets an Item or an Asset datetime.

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

Returns:

datetime or None

get_derived_from() → List[Item][source]

Get the items that this is derived from.

Returns:

Returns a reference to the derived_from items.

Return type:

List[Item]

id: str

Provider identifier. Unique within the STAC.

links: List[Link]

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

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

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

Returns:

self

Return type:

Item

classmethod matches_object_type(d: Dict[str, Any]) → bool[source]

Returns a boolean indicating whether the given dictionary represents a valid instance of this STACObject sub-class.

Parameters:

d – A dictionary to identify

properties: Dict[str, Any]

A dictionary of additional metadata for the Item.

remove_derived_from(item_id: str) → None[source]

Remove an item that this is derived from.

This method will remove from existing “derived_from” links.

Parameters:

item_id – ID of item to remove from derived_from links.

set_collection(collection: Collection | None) → Item[source]

Set the collection of this item.

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

Parameters:

collection – The collection to set as this item’s collection. If None, will clear the collection.

Returns:

self

Return type:

Item

set_datetime(datetime: Datetime, asset: Asset | None = None) → None[source]

Set an Item or an Asset datetime.

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

set_self_href(href: str | None) → None[source]

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

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

Parameters:

href – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.

stac_extensions: List[str]

List of extensions the Item implements.

to_dict(include_self_link: bool = True, transform_hrefs: bool = True) → Dict[str, Any][source]

Returns this object as a dictionary.

Parameters:

  • include_self_link – If True, the dict will contain a self link to this object. If False, the self link will be omitted.

  • transform_hrefs – If True, transform the HREF of hierarchical links based on the type of catalog this object belongs to (if any). I.e. if this object belongs to a root catalog that is RELATIVE_PUBLISHED or SELF_CONTAINED, hierarchical link HREFs will be transformed to be relative to the catalog root.

  • dict – A serialization of the object.