This is a Python project that allows you to pull your data from the Oura API using a personal access token, save it to a local PostgreSQL database, then use tools like Grafana to revisualise it. Currently the data being scraped is:
- Sleep score including score breakdown (e.g. efficiency, latency, etc)
- Sleep durations for:
- Total time in bed duration
- Total sleep duration
- REM sleep duration
- Deep sleep duration
Although last change was made approx 3 months ago - script should be working as of this edit, October 2023.
This tool was created for PERSONAL USE and such is not intended as a production-quality community tool. Use at your own risk. In my configuration, all necessary programs are running under a Rapsberry Pi running . The tool should work on other platforms such as MacOS, Windows, other Linux distriubtions. Support for other platforms will not be provided at this stage.
- Python 3.x: The project requires Python 3.x to be installed. If Python is not installed, you can download it from the official Python website: https://www.python.org/downloads/
- PostGreSQL: The project attempts to connect to a Postgres database to store its data. https://www.postgresql.org/download/
Installing Postgres is recommended first. For proper documentation, follow instructions for your platform at: https://www.postgresql.org/download/ (or consider using something like brew on macOS) or General instructions:
-
Update your package list and install postgres
sudo apt update && sudo apt install postgresql -
Switch to the postgres user using
sudo -i -u postgres
-
Access the PostgreSQL terminal by running:
psql
-
Create the database you will use to host the data (by default this tool calls it 'sleepdb')
CREATE DATABASE sleepdb;
Setting up a virtual environment is recommended to keep the project dependencies isolated. Follow these steps to set up a virtual environment. Note on MacOS you may need to follow some of the steps described in https://stackoverflow.com/questions/34304833/failed-building-wheel-for-psycopg2-macosx-using-virtualenv-and-pip
-
Change to the project directory:
cd your-repository -
Create a virtual environment:
python3 -m venv venv
-
Activate the virtual environment:
source venv/bin/activate
-
Ensure that the virtual environment is activated (if you set up one).
-
Install the project dependencies by running the following command:
pip install -r requirements.txt
- Open the
config-template.inifile in a text editor. - Fill out all configurations in the db and user sections
- Save the file.
- Set an environment variable to tell your operating system where to find this file. (Add to ~/.bashrc to not need to do this every time program is run)
export OURA_SLEEP_CONFIG_PATH="e.g. PATH/TO/YOUR/CONFIG-FILE.ini"As long as a database exists as defined in your config file, the program will create the necessary table for you.
python3 sleep-data.pyGrafana allows your to visualise data from a range of sources. Follow their guide at: https://grafana.com/docs/grafana/latest/setup-grafana/installation/
Follow this guide for connecting grafana to your postgres server https://grafana.com/docs/grafana/latest/datasources/postgres/
Create a new Visualization on your main Grafana dashboard. Set the data source to PostgreSQL. Under the 'code' query builder, you can now pull out the fields you need.
SELECT score as "Sleep Score", date FROM sleep_sessions WHERE $__timeFilter(date)- Ensure that you have followed setup instructions (above)
- Run the Python script by executing the following command:
python3 sleep-data.py- Migrated from psycopg2 to sqlalchemy to allow for more generic db handling
- Added support for pulling in sleep durations
- Various code refactoring and readability improvements
You can use a tool like cron to run the script every day.
- Add installation shell script to speed up installation.
- Look at Docker container version of tool.
- Pull in more information from Oura. At the moment only sleep data is pulled.
- checkConfig() fails if no password is set, which is a valid configuration on postgres.