Groups & Statistics

Group management, invitations, and aggregate statistics (totals, value over time, per-label and per-location breakdowns).

GroupsClient

Sub-client for group management and statistics endpoints.

Accessed via HomeboxClient.groups.

Source code in homebox/client.py

class GroupsClient:
    """Sub-client for group management and statistics endpoints.

    Accessed via ``HomeboxClient.groups``.
    """

    def __init__(self, client: HomeboxClient):
        """Initialise the groups sub-client with the shared root client."""
        self.client = client

    def get_group(self) -> Group:
        """Return the current user's group details.

        Returns:
            Group: Group information including name, currency, and timestamps.
        """
        return Group(**self.client._request("get", "/v1/groups"))

    def update_group(self, data: GroupUpdate) -> Group:
        """Update the current group's settings.

        Args:
            data: Fields to update (name and/or currency).

        Returns:
            Group: Updated group information.
        """
        return Group(**self.client._request("put", "/v1/groups", data=data.model_dump()))

    def create_group(self, data: CreateRequest) -> Group:
        """Create a new group owned by the current user."""
        return Group(**self.client._request("post", "/v1/groups", data=data.model_dump(exclude_none=True)))

    def delete_group(self):
        """Delete the current user's active group."""
        self.client._request("delete", "/v1/groups")

    def get_all_groups(self) -> list[Group]:
        """Return all groups available to the authenticated user."""
        data = self.client._request("get", "/v1/groups/all")
        return [Group(**item) for item in data.get("data", [])]

    def create_group_invitation(self, data: GroupInvitationCreate) -> GroupInvitation:
        """Create an invitation token that allows new users to join the group.

        Args:
            data: Invitation settings including expiry date and maximum number
                of uses (1–100).

        Returns:
            GroupInvitation: The generated invitation token and its metadata.
        """
        return GroupInvitation(**self.client._request("post", "/v1/groups/invitations", data=data.model_dump()))

    def get_group_invitations(self) -> list[GroupInvitation]:
        """Return all invitation tokens for the current group."""
        data = self.client._request("get", "/v1/groups/invitations")
        return [GroupInvitation(**item) for item in data.get("data", [])]

    def accept_group_invitation(self, id: str) -> GroupAcceptInvitationResponse:
        """Accept a group invitation token and join that group."""
        return GroupAcceptInvitationResponse(**self.client._request("post", f"/v1/groups/invitations/{id}"))

    def delete_group_invitation(self, id: str):
        """Delete an existing invitation token by invitation ID."""
        self.client._request("delete", f"/v1/groups/invitations/{id}")

    def get_group_members(self) -> list[UserSummary]:
        """Return all users in the current group."""
        data = self.client._request("get", "/v1/groups/members")
        return [UserSummary(**item) for item in data.get("data", [])]

    def add_group_member(self, data: GroupMemberAdd):
        """Add an existing user to the current group."""
        self.client._request("post", "/v1/groups/members", data=data.model_dump(exclude_none=True))

    def remove_group_member(self, user_id: str):
        """Remove a user from the current group by user ID."""
        self.client._request("delete", f"/v1/groups/members/{user_id}")

    def get_group_statistics(self) -> GroupStatistics:
        """Return aggregate statistics for the current group.

        Returns:
            GroupStatistics: Totals for items, labels, locations, users,
                warranted items, and total item value.
        """
        return GroupStatistics(**self.client._request("get", "/v1/groups/statistics"))

    def get_tag_statistics(self) -> list[TotalsByOrganizer]:
        """Return the total item value grouped by tag."""
        data = self.client._request("get", "/v1/groups/statistics/tags")
        if data is None:
            return []
        return [TotalsByOrganizer(**item) for item in data["data"]]

    def get_label_statistics(self) -> list[TotalsByOrganizer]:
        """Backward-compatible alias for :meth:`get_tag_statistics`."""
        return self.get_tag_statistics()

    def get_location_statistics(self) -> list[TotalsByOrganizer]:
        """Return the total item value grouped by location.

        Returns:
            list[TotalsByOrganizer]: One entry per location with the location's
                ID, name, and aggregated total value.
        """
        data = self.client._request("get", "/v1/groups/statistics/locations")

        return [TotalsByOrganizer(**item) for item in data["data"]]

    def get_purchase_price_statistics(self, start: str | None = None, end: str | None = None) -> ValueOverTime:
        """Return the cumulative purchase price of items over a date range.

        Args:
            start: Start date in ``YYYY-MM-DD`` format (inclusive).  Defaults
                to the earliest purchase date when omitted.
            end: End date in ``YYYY-MM-DD`` format (inclusive).  Defaults to
                today when omitted.

        Returns:
            ValueOverTime: Time-series data with individual entries and
                summary values at the start and end of the range.
        """
        params = {}
        if start:
            params["start"] = start
        if end:
            params["end"] = end
        return ValueOverTime(**self.client._request("get", "/v1/groups/statistics/purchase-price", params=params))

__init__

__init__(client: HomeboxClient)

Initialise the groups sub-client with the shared root client.

Source code in homebox/client.py

def __init__(self, client: HomeboxClient):
    """Initialise the groups sub-client with the shared root client."""
    self.client = client

get_group

get_group() -> Group

Return the current user's group details.

Returns:

Name	Type	Description
Group	Group	Group information including name, currency, and timestamps.

Source code in homebox/client.py

def get_group(self) -> Group:
    """Return the current user's group details.

    Returns:
        Group: Group information including name, currency, and timestamps.
    """
    return Group(**self.client._request("get", "/v1/groups"))

update_group

update_group(data: GroupUpdate) -> Group

Update the current group's settings.

Parameters:

Name	Type	Description	Default
data	GroupUpdate	Fields to update (name and/or currency).	required

Returns:

Name	Type	Description
Group	Group	Updated group information.

Source code in homebox/client.py

def update_group(self, data: GroupUpdate) -> Group:
    """Update the current group's settings.

    Args:
        data: Fields to update (name and/or currency).

    Returns:
        Group: Updated group information.
    """
    return Group(**self.client._request("put", "/v1/groups", data=data.model_dump()))

create_group

create_group(data: CreateRequest) -> Group

Create a new group owned by the current user.

Source code in homebox/client.py

def create_group(self, data: CreateRequest) -> Group:
    """Create a new group owned by the current user."""
    return Group(**self.client._request("post", "/v1/groups", data=data.model_dump(exclude_none=True)))

delete_group

delete_group()

Delete the current user's active group.

Source code in homebox/client.py

def delete_group(self):
    """Delete the current user's active group."""
    self.client._request("delete", "/v1/groups")

get_all_groups

get_all_groups() -> list[Group]

Return all groups available to the authenticated user.

Source code in homebox/client.py

def get_all_groups(self) -> list[Group]:
    """Return all groups available to the authenticated user."""
    data = self.client._request("get", "/v1/groups/all")
    return [Group(**item) for item in data.get("data", [])]

create_group_invitation

create_group_invitation(data: GroupInvitationCreate) -> GroupInvitation

Create an invitation token that allows new users to join the group.

Parameters:

Name	Type	Description	Default
data	GroupInvitationCreate	Invitation settings including expiry date and maximum number of uses (1–100).	required

Returns:

Name	Type	Description
GroupInvitation	GroupInvitation	The generated invitation token and its metadata.

Source code in homebox/client.py

def create_group_invitation(self, data: GroupInvitationCreate) -> GroupInvitation:
    """Create an invitation token that allows new users to join the group.

    Args:
        data: Invitation settings including expiry date and maximum number
            of uses (1–100).

    Returns:
        GroupInvitation: The generated invitation token and its metadata.
    """
    return GroupInvitation(**self.client._request("post", "/v1/groups/invitations", data=data.model_dump()))

get_group_invitations

get_group_invitations() -> list[GroupInvitation]

Return all invitation tokens for the current group.

Source code in homebox/client.py

def get_group_invitations(self) -> list[GroupInvitation]:
    """Return all invitation tokens for the current group."""
    data = self.client._request("get", "/v1/groups/invitations")
    return [GroupInvitation(**item) for item in data.get("data", [])]

accept_group_invitation

accept_group_invitation(id: str) -> GroupAcceptInvitationResponse

Accept a group invitation token and join that group.

Source code in homebox/client.py

def accept_group_invitation(self, id: str) -> GroupAcceptInvitationResponse:
    """Accept a group invitation token and join that group."""
    return GroupAcceptInvitationResponse(**self.client._request("post", f"/v1/groups/invitations/{id}"))

delete_group_invitation

delete_group_invitation(id: str)

Delete an existing invitation token by invitation ID.

Source code in homebox/client.py

def delete_group_invitation(self, id: str):
    """Delete an existing invitation token by invitation ID."""
    self.client._request("delete", f"/v1/groups/invitations/{id}")

get_group_members

get_group_members() -> list[UserSummary]

Return all users in the current group.

Source code in homebox/client.py

def get_group_members(self) -> list[UserSummary]:
    """Return all users in the current group."""
    data = self.client._request("get", "/v1/groups/members")
    return [UserSummary(**item) for item in data.get("data", [])]

add_group_member

add_group_member(data: GroupMemberAdd)

Add an existing user to the current group.

Source code in homebox/client.py

def add_group_member(self, data: GroupMemberAdd):
    """Add an existing user to the current group."""
    self.client._request("post", "/v1/groups/members", data=data.model_dump(exclude_none=True))

remove_group_member

remove_group_member(user_id: str)

Remove a user from the current group by user ID.

Source code in homebox/client.py

def remove_group_member(self, user_id: str):
    """Remove a user from the current group by user ID."""
    self.client._request("delete", f"/v1/groups/members/{user_id}")

get_group_statistics

get_group_statistics() -> GroupStatistics

Return aggregate statistics for the current group.

Returns:

Name	Type	Description
GroupStatistics	GroupStatistics	Totals for items, labels, locations, users, warranted items, and total item value.

Source code in homebox/client.py

def get_group_statistics(self) -> GroupStatistics:
    """Return aggregate statistics for the current group.

    Returns:
        GroupStatistics: Totals for items, labels, locations, users,
            warranted items, and total item value.
    """
    return GroupStatistics(**self.client._request("get", "/v1/groups/statistics"))

get_tag_statistics

get_tag_statistics() -> list[TotalsByOrganizer]

Return the total item value grouped by tag.

Source code in homebox/client.py

def get_tag_statistics(self) -> list[TotalsByOrganizer]:
    """Return the total item value grouped by tag."""
    data = self.client._request("get", "/v1/groups/statistics/tags")
    if data is None:
        return []
    return [TotalsByOrganizer(**item) for item in data["data"]]

get_label_statistics

get_label_statistics() -> list[TotalsByOrganizer]

Backward-compatible alias for :meth:get_tag_statistics.

Source code in homebox/client.py

def get_label_statistics(self) -> list[TotalsByOrganizer]:
    """Backward-compatible alias for :meth:`get_tag_statistics`."""
    return self.get_tag_statistics()

get_location_statistics

get_location_statistics() -> list[TotalsByOrganizer]

Return the total item value grouped by location.

Returns:

Type	Description
list[TotalsByOrganizer]	list[TotalsByOrganizer]: One entry per location with the location's ID, name, and aggregated total value.

Source code in homebox/client.py

def get_location_statistics(self) -> list[TotalsByOrganizer]:
    """Return the total item value grouped by location.

    Returns:
        list[TotalsByOrganizer]: One entry per location with the location's
            ID, name, and aggregated total value.
    """
    data = self.client._request("get", "/v1/groups/statistics/locations")

    return [TotalsByOrganizer(**item) for item in data["data"]]

get_purchase_price_statistics

get_purchase_price_statistics(start: str | None = None, end: str | None = None) -> ValueOverTime

Return the cumulative purchase price of items over a date range.

Parameters:

Name	Type	Description	Default
start	str | None	Start date in YYYY-MM-DD format (inclusive). Defaults to the earliest purchase date when omitted.	None
end	str | None	End date in YYYY-MM-DD format (inclusive). Defaults to today when omitted.	None

Returns:

Name	Type	Description
ValueOverTime	ValueOverTime	Time-series data with individual entries and summary values at the start and end of the range.

Source code in homebox/client.py

def get_purchase_price_statistics(self, start: str | None = None, end: str | None = None) -> ValueOverTime:
    """Return the cumulative purchase price of items over a date range.

    Args:
        start: Start date in ``YYYY-MM-DD`` format (inclusive).  Defaults
            to the earliest purchase date when omitted.
        end: End date in ``YYYY-MM-DD`` format (inclusive).  Defaults to
            today when omitted.

    Returns:
        ValueOverTime: Time-series data with individual entries and
            summary values at the start and end of the range.
    """
    params = {}
    if start:
        params["start"] = start
    if end:
        params["end"] = end
    return ValueOverTime(**self.client._request("get", "/v1/groups/statistics/purchase-price", params=params))