Welcome to Homeassistant API!

Homeassistant API is a pythonic module that interacts with Homeassistant’s REST API integration and Homeassistant’s Websocket API. You can use it to remotely control your Home Assistant to do things like turn on lights, change the temperature, or listen for when the garage door opens.

Index

Features

Full consumption of the Home Assistant REST API endpoints.
Full consumption of the Home Assistant Websocket API (all of the documented commands and some undocumented ones).
Convenient Pydantic Models for data validation.
Synchronous and asynchronous support for both REST and WebSocket clients.
Modular design for intuitive readability.
Request caching for more efficient repetitive requests.

Getting Started

Is this your first time using the library? Start with our Quickstart Section

Example

import os

from homeassistant_api import Client

api_url = "https://homeassistant.duckdns.org:8123/api"  # Something like http://localhost:8123/api
token = os.getenv(
    "HOMEASSISTANT_TOKEN",
)  # Used to aunthenticate yourself with homeassistant
# See the documentation on how to obtain a Long Lived Access Token


def main() -> None:
    with Client(
        api_url,
        token,
    ) as client:  # Create Client object and check that its running.
        cover = client.get_domain("cover")
        if cover is None:
            return

        # Tells Home Assistant to trigger the toggle service on the given entity_id
        cover.toggle(entity_id="cover.garage_door")


if __name__ == "__main__":
    main()

Want to look at more? Many more examples are available in the repository. We encourage you to open a pull request and add your own after you get to know the library! See the Contributing Section.

More Usage

View the documentation for each class and method here.

Contributing Guidelines

We absolutely looooooooooove contributions! This library has come a long way since its one-file humble beginning, on a Saturday afternoon with some our programming buddies. But while much has been done already there is still much much much more to do! Which is exciting! If you’re a developer that has an idea, suggestion or just wants to be helpful because you’re an awesome person. See our *newly minted* Development and Contribution page for contribution ideas, guidelines, procedures and what to expect with your PR. Happy developing! We hope to see your PRs soon.