Skip to content
Explore and analyse your Home Assistant data
Jupyter Notebook Other
Branch: master
Clone or download

Latest commit


Type Name Latest commit message Commit time
Failed to load latest commit information.
.devcontainer Tidy devcontainer Dec 31, 2019
.github adds release-drafter Dec 4, 2018
detective Address reviewer comments Jan 4, 2020
notebooks Tidy requirements Jan 5, 2020
tests Address reviewer comments Jan 4, 2020
util Tidy Jun 5, 2018
.gitignore Remove ensure_list Dec 8, 2018
.travis.yml Update .travis.yml Dec 30, 2019
LICENSE Initial commit Jan 23, 2018 Add binder back to readme Jan 4, 2020
requirements.txt Tidy requirements Jan 5, 2020
requirements_test.txt Tidy requirements Jan 5, 2020 Tidy requirements Jan 5, 2020

PyPI Version build status Binder Code style: black Sponsor


The HASS-data-detective package provides classes and functions to help you explore and analyse the data in your Home Assistant database. If you are using Hassio, it will automatically discover your database and by default collect information about the entities in your database. See the notebooks directory for examples of using the detective package.

Installation on your machine

You can either: pip install HASS-data-detective for the latest released version from pypi, or pip install git+ --upgrade for the bleeding edge version from github. Note that due to the matplotlib dependency, libfreetype6-dev is a requirement on aarch64 platforms (i.e. RPi).

Run with Docker locally

You can use the detective package within a Docker container so there is no need to install anything on your machine (assuming you already have docker installed). Note this will pull the jupyter/scipy-notebook docker image the first time you run it, but subsequent runs will be much faster.

From the root directory of this repo run:

docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "$PWD":/home/jovyan/work jupyter/scipy-notebook

Follow the URL printed to the terminal, which opens a Jupyter lab instance. Open a new terminal in Jupyter lab and navigate to the work directory containing, then run:

~/work$ pip install .

You can now navigate to the notebooks directory and start using the detective package. Note that you can install any package you want from pypi, but they will not persist on restarting the container.

Try out detective online

You can try out the latest version of detective from pypi without installing anything. If you click on the 'launch binder' button above, detective will be started in a Docker container online using the Binderhub service. Run the example notebook to explore detective, and use the Upload button to upload your own home-assistant_v2.db database file for analysis. Note that all data is deleted when the container closes down, so this service is just for trying out detective.

Auth helpers

When querying the database, you might end up with user IDs and refresh token IDs. We've included a helper to help load the auth from Home Assistant and help you process this data.

from detective.auth import auth_from_hass_config

auth = auth_from_hass_config()
  "user-id": {
    "id": "id of user",
    "name": "Name of user",
"refresh-token-id": {
  "id": "id of token",
  "user": "user object related to token",
  "client_name": "Name of client that created token",
  "client_id": "ID of client that created token",
> auth.user_name('some-user-id')


Big thanks to @balloob and @frenck, checkout their profiles!

Support this work

If you or your business find this work useful please consider becoming a sponsor at the link above, this really helps justify the time I invest in maintaining this repo. As we say in England, 'every little helps' - thanks in advance!

You can’t perform that action at this time.