fairwater API Client

Usage Guide

This guide explains how to use the FairwaterAPIClient to fetch Fairwater smart home sensor data from the API.

Installation

First, install the required dependencies:

pip install requests

Initializing the Client

You need to provide the API base URL and an API key:

from fairwater_api_client import FairwaterAPIClient
from datetime import datetime

API_BASE_URL = "https://fairapi.dev.urbanobservatory.ac.uk"
API_KEY = "your-api-key"

client = FairwaterAPIClient(API_BASE_URL, API_KEY)

---

Fetching Data

Get Droople Data (All Houses)

# Without heartbeat messages (default)
data = client.get_droople_data(datetime(2025, 1, 1), datetime(2025, 1, 2))

# Including heartbeat messages
data = client.get_droople_data(datetime(2025, 1, 1), datetime(2025, 1, 2), include_heartbeat=True)

print(data)

Get Smart Meter Data (All Houses)

data = client.get_smartmeter_data(datetime(2025, 1, 1), datetime(2025, 1, 2))
print(data)

Get Shower Data (All Houses)

data = client.get_shower_data(datetime(2025, 1, 1), datetime(2025, 1, 2))
print(data)

---

Fetching Data for a Specific House

Get Droople Data for a House

# Without heartbeat messages (default)
data = client.get_droople_data_for_house("House A", datetime(2025, 1, 1), datetime(2025, 1, 2))

# Including heartbeat messages
data = client.get_droople_data_for_house("House A", datetime(2025, 1, 1), datetime(2025, 1, 2), include_heartbeat=True)

print(data)

Get Smart Meter Data for a House

data = client.get_smartmeter_data_for_house("House A", datetime(2025, 1, 1), datetime(2025, 1, 2))
print(data)

Get Shower Data for a House

data = client.get_shower_data_for_house("House A", datetime(2025, 1, 1), datetime(2025, 1, 2))
print(data)

---

Working with Houses and Sensors

List All Houses

houses = client.get_houses()
print(houses)

Get House Details by Name

house = client.get_house("House A")
print(house)

Get Sensors for a House

sensors = client.get_house_sensors("House A")
print(sensors)