Skip to content

Item

pystac.Item

Bases: STACObject

An Item is a GeoJSON Feature augmented with foreign members relevant to a STAC object.

These include fields that identify the time range and assets of the Item. An Item is the core object in a STAC Catalog, containing the core metadata that enables any client to search or crawl online catalogs of spatial 'assets' (e.g., satellite imagery, derived data, DEMs).

Source code in src/pystac/item.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
class Item(STACObject):
    """An Item is a GeoJSON Feature augmented with foreign members relevant to a
    STAC object.

    These include fields that identify the time range and assets of the Item.
    An Item is the core object in a STAC Catalog, containing the core metadata
    that enables any client to search or crawl online catalogs of spatial
    'assets' (e.g., satellite imagery, derived data, DEMs)."""

    @classmethod
    def get_type(cls: type[Item]) -> str:
        return ITEM_TYPE

    def __init__(
        self,
        id: str,
        geometry: dict[str, Any] | None = None,
        bbox: Sequence[float | int] | None = None,
        datetime: dt.datetime
        | tuple[dt.datetime | None, dt.datetime | None]
        | str
        | tuple[str | None, str | None]
        | None = None,
        properties: dict[str, Any] | None = None,
        assets: dict[str, Asset | dict[str, Any]] | None = None,
        collection: str | None = None,
        stac_version: str | None = None,
        stac_extensions: list[str] | None = None,
        links: list[Link | dict[str, Any]] | None = None,
        **kwargs: Any,
    ) -> None:
        """Creates a new item.

        Args:
            id: The item id
            geometry: The item geometry
            bbox: The item bbox. Will be automatically set to None, with a
                warning, if the geometry is none.
            datetime: The item datetime, or start and end datetimes, as a string
                or as a datetime object.
        """
        self.geometry = geometry
        if self.geometry is None and bbox:
            warnings.warn(
                "bbox cannot be set if geometry is None. Setting bbox to None",
                STACWarning,
            )
            self.bbox = None
        else:
            self.bbox = bbox

        self.properties = properties or {}

        self.datetime: dt.datetime | None = None
        self.start_datetime: dt.datetime | None = None
        self.end_datetime: dt.datetime | None = None
        if datetime is None:
            if properties_datetime := self.properties.get("datetime", None):
                self.datetime = utils.str_to_datetime(properties_datetime)
            if properties_start_datetime := self.properties.get("start_datetime", None):
                self.start_datetime = utils.str_to_datetime(properties_start_datetime)
            if properties_end_datetime := self.properties.get("end_datetime", None):
                self.end_datetime = utils.str_to_datetime(properties_end_datetime)
            if (
                self.datetime is None
                and self.start_datetime is None
                and self.end_datetime is None
            ):
                self.datetime = dt.datetime.now(tz=dt.timezone.utc)
        elif isinstance(datetime, dt.datetime):
            self.datetime = datetime
            self.start_datetime = None
            self.end_datetime = None
        elif isinstance(datetime, tuple):
            self.datetime = None
            self.start_datetime = _parse_datetime(datetime[0])
            self.end_datetime = _parse_datetime(datetime[1])

        self.collection_id = collection

        super().__init__(
            id=id,
            stac_version=stac_version,
            stac_extensions=stac_extensions,
            links=links,
            assets=assets,
            **kwargs,
        )

    def get_fields(self) -> dict[str, Any]:
        return self.properties

    def set_collection(self, collection: Collection | None) -> None:
        if collection:
            self.collection_id = collection.id
            self.set_link(Link.collection(collection))
        else:
            self.collection_id = None
            self.remove_links(COLLECTION)

    def get_collection(self) -> Collection | None:
        from .collection import Collection

        if link := self.get_link(COLLECTION):
            stac_object = link.get_stac_object()
            if isinstance(stac_object, Collection):
                return stac_object
            else:
                return None
        else:
            return None

    def _to_dict(self) -> dict[str, Any]:
        d: dict[str, Any] = {
            "type": self.get_type(),
            "stac_version": self.stac_version,
        }
        if self.stac_extensions is not None:
            d["stac_extensions"] = self.stac_extensions
        d["id"] = self.id
        d["geometry"] = self.geometry
        if self.bbox is not None:
            d["bbox"] = self.bbox
        d["properties"] = copy.deepcopy(self.properties)

        if self.datetime is None:
            d["properties"]["datetime"] = None
        else:
            d["properties"]["datetime"] = utils.datetime_to_str(self.datetime)
        if self.start_datetime:
            d["properties"]["start_datetime"] = utils.datetime_to_str(
                self.start_datetime
            )
        if self.end_datetime:
            d["properties"]["end_datetime"] = utils.datetime_to_str(self.end_datetime)

        d["links"] = [link.to_dict() for link in self.iter_links()]
        d["assets"] = dict((key, asset.to_dict()) for key, asset in self.assets.items())
        if self.collection_id is not None:
            d["collection"] = self.collection_id
        d.update(copy.deepcopy(self.extra_fields))
        return d

__init__ 

__init__(
    id: str,
    geometry: dict[str, Any] | None = None,
    bbox: Sequence[float | int] | None = None,
    datetime: dt.datetime
    | tuple[dt.datetime | None, dt.datetime | None]
    | str
    | tuple[str | None, str | None]
    | None = None,
    properties: dict[str, Any] | None = None,
    assets: dict[str, Asset | dict[str, Any]] | None = None,
    collection: str | None = None,
    stac_version: str | None = None,
    stac_extensions: list[str] | None = None,
    links: list[Link | dict[str, Any]] | None = None,
    **kwargs: Any,
) -> None

Creates a new item.

Parameters:

Name Type Description Default
id str

The item id

 required
geometry dict[str, Any] | None

The item geometry

 None
bbox Sequence[float | int] | None

The item bbox. Will be automatically set to None, with a warning, if the geometry is none.

 None
datetime datetime | tuple[datetime | None, datetime | None] | str | tuple[str | None, str | None] | None

The item datetime, or start and end datetimes, as a string or as a datetime object.

 None
Source code in src/pystac/item.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__(
    self,
    id: str,
    geometry: dict[str, Any] | None = None,
    bbox: Sequence[float | int] | None = None,
    datetime: dt.datetime
    | tuple[dt.datetime | None, dt.datetime | None]
    | str
    | tuple[str | None, str | None]
    | None = None,
    properties: dict[str, Any] | None = None,
    assets: dict[str, Asset | dict[str, Any]] | None = None,
    collection: str | None = None,
    stac_version: str | None = None,
    stac_extensions: list[str] | None = None,
    links: list[Link | dict[str, Any]] | None = None,
    **kwargs: Any,
) -> None:
    """Creates a new item.

    Args:
        id: The item id
        geometry: The item geometry
        bbox: The item bbox. Will be automatically set to None, with a
            warning, if the geometry is none.
        datetime: The item datetime, or start and end datetimes, as a string
            or as a datetime object.
    """
    self.geometry = geometry
    if self.geometry is None and bbox:
        warnings.warn(
            "bbox cannot be set if geometry is None. Setting bbox to None",
            STACWarning,
        )
        self.bbox = None
    else:
        self.bbox = bbox

    self.properties = properties or {}

    self.datetime: dt.datetime | None = None
    self.start_datetime: dt.datetime | None = None
    self.end_datetime: dt.datetime | None = None
    if datetime is None:
        if properties_datetime := self.properties.get("datetime", None):
            self.datetime = utils.str_to_datetime(properties_datetime)
        if properties_start_datetime := self.properties.get("start_datetime", None):
            self.start_datetime = utils.str_to_datetime(properties_start_datetime)
        if properties_end_datetime := self.properties.get("end_datetime", None):
            self.end_datetime = utils.str_to_datetime(properties_end_datetime)
        if (
            self.datetime is None
            and self.start_datetime is None
            and self.end_datetime is None
        ):
            self.datetime = dt.datetime.now(tz=dt.timezone.utc)
    elif isinstance(datetime, dt.datetime):
        self.datetime = datetime
        self.start_datetime = None
        self.end_datetime = None
    elif isinstance(datetime, tuple):
        self.datetime = None
        self.start_datetime = _parse_datetime(datetime[0])
        self.end_datetime = _parse_datetime(datetime[1])

    self.collection_id = collection

    super().__init__(
        id=id,
        stac_version=stac_version,
        stac_extensions=stac_extensions,
        links=links,
        assets=assets,
        **kwargs,
    )