{"id":15651533,"url":"https://github.com/bachya/aioambient","last_synced_at":"2025-05-16T10:06:00.113Z","repository":{"id":34044576,"uuid":"164469903","full_name":"bachya/aioambient","owner":"bachya","description":"🌤 A clean, async-friendly library for interacting with the Ambient Weather API","archived":false,"fork":false,"pushed_at":"2025-02-04T20:28:48.000Z","size":1739,"stargazers_count":33,"open_issues_count":1,"forks_count":10,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2025-04-09T04:06:24.677Z","etag":null,"topics":["asyncio","pws","python3","weather","websocket-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bachya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-07T17:52:33.000Z","updated_at":"2025-02-04T20:28:52.000Z","dependencies_parsed_at":"2023-10-17T00:19:47.232Z","dependency_job_id":"2b8f158e-1283-4293-844a-54f6aa994e6d","html_url":"https://github.com/bachya/aioambient","commit_stats":{"total_commits":701,"total_committers":11,"mean_commits":63.72727272727273,"dds":"0.34807417974322397","last_synced_commit":"18e4e07bcef6b948cb4de43789ff5961ee737aad"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faioambient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faioambient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faioambient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Faioambient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bachya","download_url":"https://codeload.github.com/bachya/aioambient/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","pws","python3","weather","websocket-api"],"created_at":"2024-10-03T12:38:54.930Z","updated_at":"2025-05-16T10:06:00.084Z","avatar_url":"https://github.com/bachya.png","language":"Python","readme":"# 🌤 aioambient: An async library for Ambient Weather Personal Weather Stations\n\n[![CI][ci-badge]][ci]\n[![PyPI][pypi-badge]][pypi]\n[![Version][version-badge]][version]\n[![License][license-badge]][license]\n[![Code Coverage][codecov-badge]][codecov]\n[![Maintainability][maintainability-badge]][maintainability]\n\n\u003ca href=\"https://www.buymeacoffee.com/bachya1208P\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"\u003e\u003c/a\u003e\n\n`aioambient` is a Python3, asyncio-driven library that interfaces with both the REST and\nWebsocket APIs provided by [Ambient Weather][ambient-weather].\n\n- [Installation](#installation)\n- [Python Versions](#python-versions)\n- [API and Application Keys](#api-and-application-keys)\n- [Usage](#usage)\n- [Contributing](#contributing)\n\n# Installation\n\n```bash\npip install aioambient\n```\n\n# Python Versions\n\n`aioambient` is currently supported on:\n\n- Python 3.11\n- Python 3.12\n- Python 3.13\n\n# API and Application Keys\n\nUtilizing `aioambient` requires both an Application Key and an API Key from Ambient\nWeather. You can generate both from the Profile page in your\n[Ambient Weather Dashboard][ambient-weather-dashboard].\n\n# Usage\n\n## REST API\n\n```python\nimport asyncio\nfrom datetime import date\n\nfrom aiohttp import ClientSession\n\nfrom aioambient import API\n\n\nasync def main() -\u003e None:\n    \"\"\"Create the aiohttp session and run the example.\"\"\"\n    api = API(\"\u003cYOUR APPLICATION KEY\u003e\", \"\u003cYOUR API KEY\u003e\")\n\n    # Get all devices in an account:\n    await api.get_devices()\n\n    # Get all stored readings from a device:\n    await api.get_device_details(\"\u003cDEVICE MAC ADDRESS\u003e\")\n\n    # Get all stored readings from a device (starting at a datetime):\n    await api.get_device_details(\"\u003cDEVICE MAC ADDRESS\u003e\", end_date=date(2019, 1, 16))\n\n\nasyncio.run(main())\n```\n\nBy default, the library creates a new connection to Ambient Weather with each coroutine.\nIf you are calling a large number of coroutines (or merely want to squeeze out every\nsecond of runtime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can be used for\nconnection pooling:\n\n```python\nimport asyncio\nfrom datetime import date\n\nfrom aiohttp import ClientSession\n\nfrom aioambient import API\n\n\nasync def main() -\u003e None:\n    \"\"\"Create the aiohttp session and run the example.\"\"\"\n    async with ClientSession() as session:\n        api = API(\"\u003cYOUR APPLICATION KEY\u003e\", \"\u003cYOUR API KEY\u003e\")\n\n        # Get all devices in an account:\n        await api.get_devices()\n\n        # Get all stored readings from a device:\n        await api.get_device_details(\"\u003cDEVICE MAC ADDRESS\u003e\")\n\n        # Get all stored readings from a device (starting at a datetime):\n        await api.get_device_details(\"\u003cDEVICE MAC ADDRESS\u003e\", end_date=date(2019, 1, 16))\n\n\nasyncio.run(main())\n```\n\nPlease be aware of Ambient Weather's\n[rate limiting policies][ambient-weather-rate-limiting].\n\n## Websocket API\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom aioambient import Websocket\n\n\nasync def main() -\u003e None:\n    \"\"\"Create the aiohttp session and run the example.\"\"\"\n    websocket = Websocket(\"\u003cYOUR APPLICATION KEY\u003e\", \"\u003cYOUR API KEY\u003e\")\n\n    # Note that you can watch multiple API keys at once:\n    websocket = Websocket(\"YOUR APPLICATION KEY\", [\"\u003cAPI KEY 1\u003e\", \"\u003cAPI KEY 2\u003e\"])\n\n    # Define a method that should be fired when the websocket client\n    # connects:\n    def connect_method():\n        \"\"\"Print a simple \"hello\" message.\"\"\"\n        print(\"Client has connected to the websocket\")\n\n    websocket.on_connect(connect_method)\n\n    # Alternatively, define a coroutine handler:\n    async def connect_coroutine():\n        \"\"\"Waits for 3 seconds, then print a simple \"hello\" message.\"\"\"\n        await asyncio.sleep(3)\n        print(\"Client has connected to the websocket\")\n\n    websocket.async_on_connect(connect_coroutine)\n\n    # Define a method that should be run upon subscribing to the Ambient\n    # Weather cloud:\n    def subscribed_method(data):\n        \"\"\"Print the data received upon subscribing.\"\"\"\n        print(f\"Subscription data received: {data}\")\n\n    websocket.on_subscribed(subscribed_method)\n\n    # Alternatively, define a coroutine handler:\n    async def subscribed_coroutine(data):\n        \"\"\"Waits for 3 seconds, then print the incoming data.\"\"\"\n        await asyncio.sleep(3)\n        print(f\"Subscription data received: {data}\")\n\n    websocket.async_on_subscribed(subscribed_coroutine)\n\n    # Define a method that should be run upon receiving data:\n    def data_method(data):\n        \"\"\"Print the data received.\"\"\"\n        print(f\"Data received: {data}\")\n\n    websocket.on_data(data_method)\n\n    # Alternatively, define a coroutine handler:\n    async def data_coroutine(data):\n        \"\"\"Wait for 3 seconds, then print the data received.\"\"\"\n        await asyncio.sleep(3)\n        print(f\"Data received: {data}\")\n\n    websocket.async_on_data(data_coroutine)\n\n    # Define a method that should be run when the websocket client\n    # disconnects:\n    def disconnect_method(data):\n        \"\"\"Print a simple \"goodbye\" message.\"\"\"\n        print(\"Client has disconnected from the websocket\")\n\n    websocket.on_disconnect(disconnect_method)\n\n    # Alternatively, define a coroutine handler:\n    async def disconnect_coroutine(data):\n        \"\"\"Wait for 3 seconds, then print a simple \"goodbye\" message.\"\"\"\n        await asyncio.sleep(3)\n        print(\"Client has disconnected from the websocket\")\n\n    websocket.async_on_disconnect(disconnect_coroutine)\n\n    # Connect to the websocket:\n    await websocket.connect()\n\n    # At any point, disconnect from the websocket:\n    await websocket.disconnect()\n\n\nasyncio.run(main())\n```\n\n## Open REST API\n\nThe official REST API and Websocket API require an API and application key to access\ndata for the devices you own. This API cannot be used if you do not own a personal\nweather station.\n\nHowever, there is a second, undocumented API that is used by the https://ambientweather.net\nweb application that does not require an API and application key. You can use the\n`OpenAPI` class to retrieve weather station data from this API:\n\n```python\nimport asyncio\nfrom datetime import date\nfrom aiohttp import ClientSession\nfrom aioambient import OpenAPI\n\n\nasync def main() -\u003e None:\n    \"\"\"Create the aiohttp session and run the example.\"\"\"\n    api = OpenAPI()\n\n    # Get a list of all the devices that are located within a radius of\n    # three miles from the given latitude/longitude. Each device lists its\n    # MAC address.\n    await api.get_devices_by_location(32.5, -97.3, 3.0)\n\n    # Get the current data from a device:\n    await api.get_device_details(\"\u003cDEVICE MAC ADDRESS\u003e\")\n\n\nasyncio.run(main())\n```\n\n# Contributing\n\nThanks to all of [our contributors][contributors] so far!\n\n1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].\n2. [Fork the repository][fork].\n3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`\n4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`\n5. Install the dev environment: `script/setup`\n6. Code your new feature or bug fix on a new branch.\n7. Write tests that cover your new functionality.\n8. Run tests and ensure 100% code coverage: `pytest --cov aioambient tests`\n9. Update `README.md` with any new documentation.\n10. Submit a pull request!\n\n[aiohttp]: https://github.com/aio-libs/aiohttp\n[ambient-weather-dashboard]: https://dashboard.ambientweather.net\n[ambient-weather-rate-limiting]: https://ambientweather.docs.apiary.io/#introduction/rate-limiting\n[ambient-weather]: https://ambientweather.net\n[ci-badge]: https://img.shields.io/github/actions/workflow/status/bachya/aioambient/test.yml\n[ci]: https://github.com/bachya/aioambient/actions\n[codecov-badge]: https://codecov.io/gh/bachya/aioambient/branch/dev/graph/badge.svg\n[codecov]: https://codecov.io/gh/bachya/aioambient\n[contributors]: https://github.com/bachya/aioambient/graphs/contributors\n[fork]: https://github.com/bachya/aioambient/fork\n[issues]: https://github.com/bachya/aioambient/issues\n[license-badge]: https://img.shields.io/pypi/l/aioambient.svg\n[license]: https://github.com/bachya/aioambient/blob/main/LICENSE\n[maintainability-badge]: https://api.codeclimate.com/v1/badges/81a9f8274abf325b2fa4/maintainability\n[maintainability]: https://codeclimate.com/github/bachya/aioambient/maintainability\n[new-issue]: https://github.com/bachya/aioambient/issues/new\n[new-issue]: https://github.com/bachya/aioambient/issues/new\n[pypi-badge]: https://img.shields.io/pypi/v/aioambient.svg\n[pypi]: https://pypi.python.org/pypi/aioambient\n[version-badge]: https://img.shields.io/pypi/pyversions/aioambient.svg\n[version]: https://pypi.python.org/pypi/aioambient\n","funding_links":["https://www.buymeacoffee.com/bachya1208P"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbachya%2Faioambient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbachya%2Faioambient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbachya%2Faioambient/lists"}