Package: aioambient
🌤 aioambient: An async library for Ambient Weather Personal Weather Stationsaioambientis a Python3, asyncio-driven library that interfaces with both the REST and
Websocket APIs provided byAmbient Weather.InstallationPython VersionsAPI and Application KeysUsageContributingInstallationpipinstallaioambientPython Versionsaioambientis currently supported on:Python 3.10Python 3.11Python 3.12API and Application KeysUtilizingaioambientrequires both an Application Key and an API Key from Ambient
Weather. You can generate both from the Profile page in yourAmbient Weather Dashboard.UsageREST APIimportasynciofromdatetimeimportdatefromaiohttpimportClientSessionfromaioambientimportAPIasyncdefmain()->None:"""Create the aiohttp session and run the example."""api=API("<YOUR APPLICATION KEY>","<YOUR API KEY>")# Get all devices in an account:awaitapi.get_devices()# Get all stored readings from a device:awaitapi.get_device_details("<DEVICE MAC ADDRESS>")# Get all stored readings from a device (starting at a datetime):awaitapi.get_device_details("<DEVICE MAC ADDRESS>",end_date=date(2019,1,16))asyncio.run(main())By default, the library creates a new connection to Ambient Weather with each coroutine.
If you are calling a large number of coroutines (or merely want to squeeze out every
second of runtime savings possible), anaiohttpClientSessioncan be used for
connection pooling:importasynciofromdatetimeimportdatefromaiohttpimportClientSessionfromaioambientimportAPIasyncdefmain()->None:"""Create the aiohttp session and run the example."""asyncwithClientSession()assession:api=API("<YOUR APPLICATION KEY>","<YOUR API KEY>")# Get all devices in an account:awaitapi.get_devices()# Get all stored readings from a device:awaitapi.get_device_details("<DEVICE MAC ADDRESS>")# Get all stored readings from a device (starting at a datetime):awaitapi.get_device_details("<DEVICE MAC ADDRESS>",end_date=date(2019,1,16))asyncio.run(main())Please be aware of Ambient Weather'srate limiting policies.Websocket APIimportasynciofromaiohttpimportClientSessionfromaioambientimportWebsocketasyncdefmain()->None:"""Create the aiohttp session and run the example."""websocket=Websocket("<YOUR APPLICATION KEY>","<YOUR API KEY>")# Note that you can watch multiple API keys at once:websocket=Websocket("YOUR APPLICATION KEY",["<API KEY 1>","<API KEY 2>"])# Define a method that should be fired when the websocket client# connects:defconnect_method():"""Print a simple "hello" message."""print("Client has connected to the websocket")websocket.on_connect(connect_method)# Alternatively, define a coroutine handler:asyncdefconnect_coroutine():"""Waits for 3 seconds, then print a simple "hello" message."""awaitasyncio.sleep(3)print("Client has connected to the websocket")websocket.async_on_connect(connect_coroutine)# Define a method that should be run upon subscribing to the Ambient# Weather cloud:defsubscribed_method(data):"""Print the data received upon subscribing."""print(f"Subscription data received:{data}")websocket.on_subscribed(subscribed_method)# Alternatively, define a coroutine handler:asyncdefsubscribed_coroutine(data):"""Waits for 3 seconds, then print the incoming data."""awaitasyncio.sleep(3)print(f"Subscription data received:{data}")websocket.async_on_subscribed(subscribed_coroutine)# Define a method that should be run upon receiving data:defdata_method(data):"""Print the data received."""print(f"Data received:{data}")websocket.on_data(data_method)# Alternatively, define a coroutine handler:asyncdefdata_coroutine(data):"""Wait for 3 seconds, then print the data received."""awaitasyncio.sleep(3)print(f"Data received:{data}")websocket.async_on_data(data_coroutine)# Define a method that should be run when the websocket client# disconnects:defdisconnect_method(data):"""Print a simple "goodbye" message."""print("Client has disconnected from the websocket")websocket.on_disconnect(disconnect_method)# Alternatively, define a coroutine handler:asyncdefdisconnect_coroutine(data):"""Wait for 3 seconds, then print a simple "goodbye" message."""awaitasyncio.sleep(3)print("Client has disconnected from the websocket")websocket.async_on_disconnect(disconnect_coroutine)# Connect to the websocket:awaitwebsocket.connect()# At any point, disconnect from the websocket:awaitwebsocket.disconnect()asyncio.run(main())Open REST APIThe official REST API and Websocket API require an API and application key to access
data for the devices you own. This API cannot be used if you do not own a personal
weather station.However, there is a second, undocumented API that is used by thehttps://ambientweather.netweb application that does not require an API and application key. You can use theOpenAPIclass to retrieve weather station data from this API:importasynciofromdatetimeimportdatefromaiohttpimportClientSessionfromaioambientimportOpenAPIasyncdefmain()->None:"""Create the aiohttp session and run the example."""api=OpenAPI()# Get a list of all the devices that are located within a radius of# three miles from the given latitude/longitude. Each device lists its# MAC address.awaitapi.get_devices_by_location(32.5,-97.3,3.0)# Get the current data from a device:awaitapi.get_device_details("<DEVICE MAC ADDRESS>")asyncio.run(main())ContributingThanks to all ofour contributorsso far!Check for open features/bugsorinitiate a discussion on one.Fork the repository.(optional, but highly recommended) Create a virtual environment:python3 -m venv .venv(optional, but highly recommended) Enter the virtual environment:source ./.venv/bin/activateInstall the dev environment:script/setupCode your new feature or bug fix on a new branch.Write tests that cover your new functionality.Run tests and ensure 100% code coverage:poetry run pytest --cov aioambient testsUpdateREADME.mdwith any new documentation.Submit a pull request!