googlewifiapi

An asynchronous Python client for reading status from the local JSON API exposed by Google Wifi routers. The package is designed for integrations such as Home Assistant, but can be used by any Python application that needs router status data.

About this README

This README was generated by AI with human review. All code is either written by a human or is thoroughly reviewed. I'll try to keep the README updated, but sometimes I might forget.

Requirements

• Python 3.13 or newer
• A Google Wifi router reachable on the local network

Installation

pip install googlewifiapi

Usage

Pass an aiohttp.ClientSession to the client so your application controls the session lifecycle:

import asyncio

import aiohttp

from googlewifiapi import GoogleWifiAPI


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        router = GoogleWifiAPI(host="192.168.86.1", sess=session)
        await router.async_update()

        if router.data is not None:
            print(router.data.wan.online)
            print(router.data.software.software_version)
            print(router.data.system.last_restart)


asyncio.run(main())

The host defaults to 192.168.86.1. After a successful update:

• router.raw_data contains the raw JSON response.
• router.data contains a validated, typed GoogleWifiStatus.
• IP address fields are parsed as IPv4Address or IPv6Address objects.
• system.last_restart is calculated from the router's uptime.

The status object exposes dns, software, system, and wan sections. Their fields use Python names such as software_version, gateway_ip_address, and ip_prefix_length, while the client handles the router API's camelCase keys.

Errors

All library errors inherit from GoogleWifiException:

• GoogleWifiClientError indicates a request, connection, timeout, or JSON decoding failure.
• GoogleWifiDataValidationError indicates that the response does not match the expected status schema.

Development

Install the test dependencies and run the test suite with uv:

uv sync --group test
uv run pytest

License

This project is licensed under the MIT License. See LICENSE.txt.

Disclaimer

This is an independent, community-developed project and is not affiliated with or endorsed by Google LLC. It relies on a local API that Google may change or remove without notice.