API documentation

The following documentation is based on the source code of version 1.0.0 of the blueair package.

The blueair module

Unofficial Blueair Python client.

class blueair.BlueAir(username: str, password: str, home_host: Optional[str] = None, auth_token: Optional[str] = None)

This class provides API calls to interact with the Blueair API.

__init__(username: str, password: str, home_host: Optional[str] = None, auth_token: Optional[str] = None) → None

Instantiate a new Blueair client with the provided username and password.

To optimize multiple instantiatons of this class a server hostname and authentication token can be provided. This will cause the client to reuse a session from a previously initialized client and saves up to two API calls.

get_home_host() → str

Retrieve the home host for the current username.

The home host is the server that is used to interact with the Blueair device. It can be stored and reused to avoid requesting it again when reinitializing the class at a later time.

get_auth_token() → str

Authenticate the user and retrieve the authentication token.

The authentication token can be reused to prevent an additional network request when initializing the client.

api_call(path: str) → Any

Perform a Blueair API call.

This is a low level function that is used by most of the client API calls.

get_devices() → List[Dict[str, Any]]

Fetch a list of devices.

Returns a list of dictionaries. Each dictionary will have a UUID key (the device identifier), a user ID, MAC address, and device name.

Example response:

[{“uuid”:”1234567890ABCDEF”,”userId”:12345,”mac”:”1234567890AB”,”name”:”My Blueair Device”}]

get_attributes(device_uuid: str) → Dict[str, Any]

Fetch a list of attributes for the provided device ID.

The return value is a dictionary containing key-value pairs for any available attributes.

Note: the data for this API call is only updated once every 5 minutes. Calling it more often will return the same respone from the server and should be avoided to limit server load.

get_info(device_uuid: str) → Dict[str, Any]

Fetch device information for the provided device ID.

The return value is a dictionary containing key-value pairs for the available device information.

Note: the data for this API call is only updated once every 5 minutes. Calling it more often will return the same respone from the server and should be avoided to limit server load.

get_current_data_point(device_uuid: str) → Mapping[str, Union[int, float]]

Fetch the most recent data point for the provided device ID.

Returns a dictionary containing a key-value mapping for the most recent measurements.

Note: the data for this API call is only updated once every 5 minutes. Calling it more often will return the same respone from the server and should be avoided to limit server load.

__weakref__

list of weak references to the object (if defined)

get_data_points_since(device_uuid: str, seconds_ago: int = 0, sample_period: int = 0) → List[Mapping[str, Union[int, float]]]

Fetch the list of data points between a relative timestamp (in seconds) and the current time.

An optional sample period can be provided to group data points together. The minimum sample period size is 300 (5 minutes).

Note: the data for the most recent data point is only updated once every 5 minutes. Calling it more often will return the same respone from the server and should be avoided to limit server load.

get_data_points_between(device_uuid: str, start_timestamp: int, end_timestamp: int, sample_period: int = 0) → List[Mapping[str, Union[int, float]]]

Fetch the list of data points between two timestamps.

The start and end timestamp are specified in seconds since the Unix epoch.

An optional sample period can be provided to group data points together. The minimum sample period size is 300 (5 minutes).

Note: the data for the most recent data point is only updated once every 5 minutes. Calling it more often will return the same respone from the server and should be avoided to limit server load.