Code Reference

Interact with your Homeassistant Instance remotely.

class homeassistant_api.Client(api_url, token, use_async=False, verify_ssl=True, **kwargs)

The all-in-one class to interact with Home Assistant!

Parameters:

api_url (str) – The location of the api endpoint. e.g. http://localhost:8123/api Required.
token (str) – The refresh or long lived access token to authenticate your requests. Required.
global_request_kwargs – A dictionary or dict-like object of kwargs to pass to requests.request() or aiohttp.ClientSession.request(). Optional.
cache_session – A requests_cache.CachedSession object to use for caching requests. Optional.
async_cache_session – A aiohttp_client_cache.CachedSession object to use for caching requests. Optional.

async async_check_api_config()

Asks Home Assistant to validate its configuration file and returns true/false. POST /api/config/core/check_config

Return type:: bool

async async_check_api_running()

Asks Home Assistant if its running. GET /api/

Return type:: bool

async async_fire_event(event_type, **event_data)

Fires a given event_type within homeassistant. Must be an existing event_type. POST /api/events/<event_type>

Return type:: str

async async_get_components()

Returns a tuple of all registered components. GET /api/components

Return type:: Tuple[str, ...]

async async_get_config()

Returns the yaml configuration of homeassistant. GET /api/config

Return type:: dict[str, TypeAliasType]

async async_get_domain(domain_id)

Fetches all Service’s under a particular service Domain. Uses cached data from get_domains() if available.

Return type:: Optional[Domain]

async async_get_domains()

Fetches all Service ‘s from the API. GET /api/services

Return type:: Dict[str, Domain]

async async_get_entities()

Fetches all entities from the api. GET /api/states

Return type:: Dict[str, Group]

async async_get_entity(group_id=None, slug=None, entity_id=None)

Returns a Entity model for an entity_id. GET /api/states/<entity_id>

Return type:: Optional[Entity]

async async_get_entity_histories(entities=None, start_timestamp=None, end_timestamp=None, significant_changes_only=False)

Returns a generator of entity state histories from homeassistant. GET /api/history/period/<timestamp>

Return type:: AsyncGenerator[History, None]

async async_get_error_log()

Returns the server error log as a string. GET /api/error_log

Return type:: str

async async_get_event(name)

Gets the Event with the specified name if it has at least one listener. Uses cached data from get_events() if available.

Return type:: Optional[Event]

async async_get_events()

Gets the Events that happen within homeassistant GET /api/events

Return type:: Tuple[Event, ...]

async async_get_logbook_entries(*args, **kwargs)

Returns a list of logbook entries from homeassistant. GET /api/logbook/<timestamp>

Return type:: AsyncGenerator[LogbookEntry, None]

async async_get_rendered_template(template)

Renders a given Jinja2 template string with Home Assistant context data. POST /api/template

Return type:: str

async async_get_state(*, entity_id=None, group_id=None, slug=None)

Fetches the state of the entity specified. GET /api/states/<entity_id>

Return type:: State

async async_get_states()

Gets the states of all entities within homeassistant. GET /api/states

Return type:: Tuple[State, ...]

async async_request(path, *, params='', method='GET', headers=None, **kwargs)

Base method for making requests to the api

Return type:: Any

async static async_response_logic(response)

Processes custom mimetype content asyncronously.

Return type:: Any

async async_set_state(state)

This method sets the representation of a device within Home Assistant and will not communicate with the actual device. To communicate with the device, use Service.trigger() or Service.async_trigger(). POST /api/states/<entity_id>

Return type:: State

async async_trigger_service(domain, service, **service_data)

Tells Home Assistant to trigger a service, returns all states changed while in the process of being called. POST /api/services/<domain>/<service>

Return type:: Tuple[State, ...]

async async_trigger_service_with_response(domain, service, **service_data)

Tells Home Assistant to trigger a service, returns the response from the service call. POST /api/services/<domain>/<service>

Returns a list of the states changed and the response from the service call.

Return type:: tuple[tuple[State, ...], dict[str, TypeAliasType]]

check_api_config()

Asks Home Assistant to validate its configuration file. POST /api/config/core/check_config

Return type:: bool

check_api_running()

Asks Home Assistant if it is running. GET /api/

Return type:: bool

static construct_params(params)

Custom method for constructing non-standard query strings.

For keys with corresponding None values, the query string will be key only (i.e. ?key1&key2). For keys with corresponding non-None values, the query string will be key-value pairs (i.e. ?key1=value1&key2=value2). To have an empty value use an empty string "" (i.e. ?key1=&key2=value2).

Return type:: str

endpoint(*path)

Joins the api base url with a local path to an absolute url

Return type:: str

fire_event(event_type, **event_data)

Fires a given event_type within homeassistant. Must be an existing event_type. POST /api/events/<event_type>

Return type:: Optional[str]

get_components()

Returns a tuple of all registered components. GET /api/components

Return type:: Tuple[str, ...]

get_config()

Returns the yaml configuration of homeassistant. GET /api/config

Return type:: dict[str, TypeAliasType]

get_domain(domain_id)

Fetches all Service’s under a particular service Domain. Uses cached data from get_domains() if available.

Return type:: Optional[Domain]

get_domains()

Fetches all Service ‘s from the API. GET /api/services

Return type:: Dict[str, Domain]

get_entities()

Fetches all entities from the api and returns them as a dictionary of Group’s. GET /api/states

Return type:: Dict[str, Group]

get_entity(group_id=None, slug=None, entity_id=None)

Returns an Entity model for an entity_id. GET /api/states/<entity_id>

Return type:: Optional[Entity]

get_entity_histories(entities=None, start_timestamp=None, end_timestamp=None, significant_changes_only=False)

Yields entity state histories. See docs on the History model. GET /api/history/period/<timestamp>

Return type:: Generator[History, None, None]

get_error_log()

Returns the server error log as a string. GET /api/error_log

Return type:: str

get_event(name)

Gets the Event with the specified name if it has at least one listener. Uses cached data from get_events() if available.

Return type:: Optional[Event]

get_events()

Gets the Events that happen within homeassistant GET /api/events

Return type:: Tuple[Event, ...]

get_logbook_entries(*args, **kwargs)

Returns a list of logbook entries from homeassistant. GET /api/logbook/<timestamp>

Return type:: Generator[LogbookEntry, None, None]

get_rendered_template(template)

Renders a Jinja2 template with Home Assistant context data. See https://www.home-assistant.io/docs/configuration/templating. POST /api/template

Return type:: str

get_state(*, entity_id=None, group_id=None, slug=None)

Fetches the state of the entity specified. GET /api/states/<entity_id>

Return type:: State

get_states()

Gets the states of all entities within homeassistant. GET /api/states

Return type:: Tuple[State, ...]

static prepare_get_entity_histories_params(entities=None, start_timestamp=None, end_timestamp=None, significant_changes_only=False)

Pre-logic for Client.get_entity_histories() and Client.async_get_entity_histories().

Ensure timestamps :rtype: Tuple[Dict[str, Optional[str]], str]

use second resolution (microseconds are truncated)
are timezone-aware
are URL-encoded (as construct_params() is used instead of request’s default parameter encoding)

static prepare_get_logbook_entry_params(filter_entities=None, start_timestamp=None, end_timestamp=None)

Prepares the query string and url path for retrieving logbook entries.

Return type:: Tuple[Dict[str, str], str]

prepare_headers(headers=None)

Prepares and verifies dictionary headers.

Return type:: Dict[str, str]

request(path, *, params='', method='GET', headers=None, decode_bytes=True, **kwargs)

Base method for making requests to the api

Return type:: Any

classmethod response_logic(response, decode_bytes=True)

Processes responses from the API and formats them

Return type:: Any

set_state(state)

This method sets the representation of a device within Home Assistant and will not communicate with the actual device. To communicate with the device, use Service.trigger() or Service.async_trigger(). POST /api/states/<entity_id>

Return type:: State

trigger_service(domain, service, **service_data)

Tells Home Assistant to trigger a service, returns all states changed while in the process of being called. POST /api/services/<domain>/<service>

Return type:: Tuple[State, ...]

trigger_service_with_response(domain, service, **service_data)

Tells Home Assistant to trigger a service, returns the response from the service call. POST /api/services/<domain>/<service>

Returns a list of the states changed and the response from the service call.

Return type:: tuple[tuple[State, ...], dict[str, TypeAliasType]]

pydantic model homeassistant_api.State

A model representing a state of an entity.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

attributes (dict[str, JSONType])
context (homeassistant_api.models.states.Context | None)
entity_id (str)
last_changed (datetime.datetime)
last_reported (datetime.datetime | None)
last_updated (datetime.datetime | None)
state (str)

field entity_id: str [Required]: The entity_id this state corresponds to.

field state: str [Required]: The string representation of the state of the entity.

field attributes: dict[str, TypeAliasType] = {}: A dictionary of extra attributes of the state.

field last_changed: Annotated[datetime] [Optional]

The last time the state was changed.

Constraints:

func = <function <lambda> at 0x7c1a60141360>
return_type = <class ‘str’>
when_used = json

field last_updated: Optional[Annotated[datetime]] [Optional]: The last time the state updated.

field last_reported: Optional[Annotated[datetime]] [Optional]: The last time the state was reported to the server. Only used by some integrations.

field context: Optional[Context] = None: Provides information about the context of the state.

classmethod from_json(json)

Constructs State model from json data

Return type:: State

pydantic model homeassistant_api.Context

Model for entity state contexts.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

id (str)
parent_id (str | None)
user_id (str | None)

field id: str [Required]

Unique string identifying the context.

Constraints:

max_length = 128

field parent_id: Optional[str] [Required]

Unique string identifying the parent context.

Constraints:

max_length = 128

field user_id: Optional[str] [Required]

Unique string identifying the user.

Constraints:

max_length = 128

classmethod from_json(json)

Constructs Context model from json data

Return type:: Context

pydantic model homeassistant_api.Domain

Model representing the domain that services belong to.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

domain_id (str)
services (Dict[str, homeassistant_api.models.domains.Service])

field domain_id: str [Required]: The name of the domain that services belong to. (e.g. frontend in frontend.reload_themes

field services: Dict[str, 'Service'] = {}: A dictionary of all services belonging to the domain indexed by their names

classmethod from_json(json, client)

Constructs Domain and Service models from json data.

Return type:: Domain

get_service(service_id)

Return a Service with the given service_id, returns None if no such service exists

Return type:: Optional[Service]

pydantic model homeassistant_api.Service

Model representing services from homeassistant

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

description (str | None)
domain (homeassistant_api.models.domains.Domain)
fields (Dict[str, homeassistant_api.models.domains.ServiceField | homeassistant_api.models.domains.ServiceFieldCollection] | None)
name (str)
response (homeassistant_api.models.domains.ServiceResponse | None)
service_id (str)
target (homeassistant_api.models.domains.ServiceFieldSelectorTarget | None)

field service_id: str [Required]

field domain: Domain [Required]

field name: str [Required]

field description: Optional[str] = None

field fields: Optional[Dict[str, Union[ServiceField, ServiceFieldCollection]]] = None

field target: Optional[ServiceFieldSelectorTarget] = None

field response: Optional[ServiceResponse] = None

trigger(**service_data)

Triggers the service associated with this object.

Return type:: Union[Tuple[State, ...], Tuple[Tuple[State, ...], dict[str, TypeAliasType]], dict[str, TypeAliasType], None]

async async_trigger(**service_data)

Triggers the service associated with this object.

Return type:: Union[Tuple[State, ...], Tuple[Tuple[State, ...], dict[str, TypeAliasType]]]

pydantic model homeassistant_api.Group

Represents the groups that entities belong to.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

entities (Dict[str, homeassistant_api.models.entity.Entity])
group_id (str)

field group_id: str [Required]: A unique string identifying different types/groups of entities.

field entities: Dict[str, Entity] = {}: A dictionary of all entities belonging to the group indexed by their entity_id.

get_entity(slug)

Returns Entity with the given name if it exists. Otherwise returns None

Return type:: Optional[Entity]

pydantic model homeassistant_api.Entity

Represents entities inside of homeassistant

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

group (homeassistant_api.models.entity.Group)
slug (str)
state (homeassistant_api.models.states.State)

field slug: str [Required]

field state: State [Required]

field group: Group [Required]

get_state()

Asks Home Assistant for the state of the entity and updates it locally

Return type:: State

update_state()

Tells Home Assistant to set its current local State object. (You can modify the local state object yourself.)

Return type:: State

property entity_id: str: Constructs the entity_id string from its group and slug

get_history(start_timestamp=None, end_timestamp=None, significant_changes_only=False)

Gets the previous State’s of the Entity

Return type:: Optional[History]

async async_get_state()

Asks Home Assistant for the state of the entity and sets it locally

Return type:: State

async async_update_state()

Tells Home Assistant to set the current local State object.

Return type:: State

async async_get_history(start_timestamp=None, end_timestamp=None, significant_changes_only=False)

Gets the History of previous State’s of the Entity.

Return type:: Optional[History]

pydantic model homeassistant_api.History

Model representing past State’s of an entity.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

states (Tuple[homeassistant_api.models.states.State, ...])

field states: Tuple[State, ...] [Required]: A tuple of previous states of an entity.

property entity_id: str: Returns the shared entity_id of states.

pydantic model homeassistant_api.Event

Event class for Home Assistant Event Triggers

For attribute information see the Data Science docs on Event models https://data.home-assistant.io/docs/events

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

event (str)
listener_count (int)

field event: str [Required]: The event name/type.

field listener_count: int [Required]: How many listeners are interesting in this event in Home Assistant.

fire(**event_data)

Fires the corresponding event in Home Assistant.

Return type:: Optional[str]

async async_fire(**event_data)

Fires the event type in homeassistant. Ex. on_startup

Return type:: str

classmethod from_json(json, client)

Constructs Event model from json data

Return type:: Event

pydantic model homeassistant_api.LogbookEntry

Model representing entries in the Logbook.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

context_id (str | None)
domain (str | None)
entity_id (str | None)
icon (str | None)
message (str | None)
name (str)
state (str | None)
when (datetime.datetime)

field when: Annotated[datetime] [Required]

When the entry was logged.

Constraints:

func = <function <lambda> at 0x7c1a60141360>
return_type = <class ‘str’>
when_used = json

field name: str [Required]: The name of the entry.

field message: Optional[str] = None: Optional message for the entry.

field entity_id: Optional[str] = None: Optional relevant entity_id.

field state: Optional[str] = None: The new state information of the entity_id.

field domain: Optional[str] = None: When the entry was logged.

field context_id: Optional[str] = None: Optional relevant context instead of an entity.

field icon: Optional[str] = None: An MDI icon associated with the entity_id.

class homeassistant_api.WebsocketClient(api_url, token)

The main class for interactign with the Home Assistant WebSocket API client.

Here’s a quick example of how to use the WebsocketClient class:

from homeassistant_api import WebsocketClient

with WebsocketClient(
    '<WS API Server URL>', # i.e. 'ws://homeassistant.local:8123/api/websocket'
    '<Your Long Lived Access-Token>'
) as ws_client:
    light = ws_client.trigger_service('light', 'turn_on', entity_id="light.living_room")

get_rendered_template(template)

Renders a Jinja2 template with Home Assistant context data. See https://www.home-assistant.io/docs/configuration/templating.

Sends command {"type": "render_template", ...}.

Return type:: str

get_config()

Get the Home Assistant configuration.

Sends command {"type": "get_config", ...}.

Return type:: dict[str, TypeAliasType]

get_states()

Get a list of states.

Sends command {"type": "get_states", ...}.

Return type:: Tuple[State, ...]

get_state(*, entity_id=None, group_id=None, slug=None)

Just calls the get_states() method and filters the result.

Please tell home-assistant/core to add a {"type": "get_state", ...} command to the WS API! There is a lot of disappointment and frustration in the community because this is not available.

Return type:: State

get_entities()

Fetches all entities from the Websocket API and returns them as a dictionary of Group’s. For example light.living_room would be in the group light (i.e. get_entities()["light"].living_room).

Return type:: Dict[str, Group]

get_entity(group_id=None, slug=None, entity_id=None)

Returns an Entity model for an entity_id.

Calls get_states() under the hood.

Please tell home-assistant/core to add a {"type": "get_state", ...} command to the WS API! There is a lot of disappointment and frustration in the community because this is not available.

Return type:: Optional[Entity]

get_domains()

Get a list of services that Home Assistant offers (organized into a dictionary of service domains).

For example, the service light.turn_on would be in the domain light.

Sends command {"type": "get_services", ...}.

Return type:: dict[str, Domain]

get_domain(domain)

Get a domain.

Note: This is not a method in the WS API client… yet.

Please tell home-assistant/core to add a get_domain command to the WS API!

For now, just call the :py:meth”:get_domains method and parsing the result.

Return type:: Domain

trigger_service(domain, service, entity_id=None, **service_data)

Trigger a service (that doesn’t return a response).

Sends command {"type": "call_service", ...}.

Return type:: None

trigger_service_with_response(domain, service, entity_id=None, **service_data)

Trigger a service (that returns a response) and return the response.

Sends command {"type": "call_service", ...}.

Return type:: dict[str, TypeAliasType]

listen_events(event_type=None)

Listen for all events of a certain type.

For example, to listen for all events of type test_event:

with ws_client.listen_events("test_event") as events:
    for i, event in zip(range(2), events):  # to only wait for two events to be received
        print(event)

Return type:: Generator[Generator[FiredEvent, None, None], None, None]

listen_trigger(trigger, **trigger_fields)

Listen to a Home Assistant trigger. Allows additional trigger keyword parameters with **kwargs (i.e. passing tag_id=... for NFC tag triggers).

For example, in Home Assistant Automations we can subscribe to a state trigger for a light entity with YAML:

triggers:
# ...
- trigger: state
  entity_id: light.kitchen

To subscribe to that same state trigger with WebsocketClient instead

with ws_client.listen_trigger("state", entity_id="light.kitchen") as trigger:
    for event in trigger:  # will iterate until we manually break out of the loop
        print(event)
        if <some_condition>:
            break
    # exiting the context manager unsubscribes from the trigger

Woohoo! We can now listen to triggers in Python code!

Return type:: Generator[Generator[dict[str, TypeAliasType], None, None], None, None]

fire_event(event_type, **event_data)

Fire an event.

Sends command {"type": "fire_event", ...}.

Return type:: Context

authentication_phase()

Authenticate with the websocket server.

Return type:: AuthOk

check_success(data)

Check if a command message was successful.

Return type:: None

handle_recv(data)

Handle a received message.

Return type:: None

ping_latency()

Get the latency (in milliseconds) of the connection by sending a ping message.

Return type:: float

recv(id)

Receive a response to a message from the websocket server.

Return type:: Union[EventResponse, ResultResponse, PingResponse]

send(type, include_id=True, **data)

Send a command message to the websocket server and wait for a “result” response.

Returns the id of the message sent.

Return type:: int

supported_features_phase()

Get the supported features from the websocket server.

Return type:: None

pydantic model homeassistant_api.AuthInvalid

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

message (str)
type (Literal['auth_invalid'])

field type: Literal['auth_invalid'] [Required]

field message: str [Required]

pydantic model homeassistant_api.AuthOk

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

ha_version (str)
type (Literal['auth_ok'])

field type: Literal['auth_ok'] [Required]

field ha_version: str [Required]

pydantic model homeassistant_api.AuthRequired

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

ha_version (str)
type (Literal['auth_required'])

field type: Literal['auth_required'] [Required]

field ha_version: str [Required]

pydantic model homeassistant_api.ResultResponse

Result websocket response model.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

id (int)
result (Any | None)
success (Literal[True])
type (Literal['result'])

field id: int [Required]

field success: Literal[True] [Required]

field type: Literal['result'] [Required]

field result: Optional[Any] [Required]

pydantic model homeassistant_api.ErrorResponse

Error websocket response model.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

error (homeassistant_api.models.websocket.Error)
id (int)
success (Literal[False])
type (Literal['result'])

field id: int [Required]

field success: Literal[False] [Required]

field type: Literal['result'] [Required]

field error: Error [Required]

pydantic model homeassistant_api.PingResponse

Ping websocket response model.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

end (int | None)
id (int)
start (int)
type (Literal['pong'])

field id: int [Required]

field type: Literal['pong'] [Required]

field start: int [Required]

field end: Optional[int] = None

pydantic model homeassistant_api.EventResponse

A model to parse the response of a fired event websocket response.

Config:

arbitrary_types_allowed: bool = True
validate_assignment: bool = True
extra: str = forbid
protected_namespaces: tuple = ()

Fields:

event (homeassistant_api.models.websocket.FiredEvent | homeassistant_api.models.websocket.FiredTrigger | homeassistant_api.models.websocket.TemplateEvent)
id (int)
type (Literal['event'])

field id: int [Required]

field type: Literal['event'] [Required]

field event: Union[FiredEvent, FiredTrigger, TemplateEvent] [Required]