{"id":50992176,"url":"https://github.com/ageron/quicnz","last_synced_at":"2026-06-20T04:32:26.654Z","repository":{"id":359485502,"uuid":"1246236438","full_name":"ageron/quicnz","owner":"ageron","description":"Async Python library for the Quic broadband API (unofficial)","archived":false,"fork":false,"pushed_at":"2026-05-30T23:10:22.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T01:09:33.124Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/ageron.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T02:19:12.000Z","updated_at":"2026-05-30T23:10:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ageron/quicnz","commit_stats":null,"previous_names":["ageron/quicnz"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ageron/quicnz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageron%2Fquicnz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageron%2Fquicnz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageron%2Fquicnz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageron%2Fquicnz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ageron","download_url":"https://codeload.github.com/ageron/quicnz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ageron%2Fquicnz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34557551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-06-20T04:32:25.953Z","updated_at":"2026-06-20T04:32:26.646Z","avatar_url":"https://github.com/ageron.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# quicnz\n\nAsync Python library for the [Quic broadband](https://quic.nz) API.\n\nQuic exposes an API at `https://api.quic.nz/v1/` that gives customers access\nto their service configuration, live session data (connection status, assigned\nIP addresses, PPPoE/DHCP details), and a network weather map.  This library\nwraps that API with a clean, fully-typed async interface built on\n[aiohttp](https://docs.aiohttp.org/).\n\n\u003e **Home Assistant integration:** A separate `ha-quicnz` custom integration\n\u003e that uses this library as a dependency is maintained at\n\u003e https://github.com/ageron/ha-quicnz\n\n\u003e **Disclaimer:** This project is an independent, community-maintained library\n\u003e and is **not affiliated with, endorsed by, or supported by Quic Broadband /\n\u003e Vetta Trading Ltd** in any way.  Use it at your own risk.\n\n---\n\n## Requirements\n\n- Python 3.11+\n- aiohttp ≥ 3.9\n\n## Installation\n\n```bash\npip install quicnz\n```\n\n## Getting an API key\n\nLog in to the [Quic portal](https://account.quic.nz/), select a service, navigate to the bottom of the page, below your product details, and you should find your API key. If the field is empty, click \"Roll API Key\" to generate the key.\n\n## Quick start\n\n```python\nimport asyncio\nfrom quicnz import QuicClient\n\nasync def main():\n    # api_key can also be supplied via the QUICNZ_API_KEY environment variable\n    async with QuicClient(api_key=\"YOUR_API_KEY\") as client:\n        # List all services associated with your account\n        service_ids = await client.get_services()\n        print(\"Services:\", service_ids)\n\n        # Fetch the active session for the first service\n        session = await client.get_session(service_ids[0])\n        print(\"Connected:\", session.is_connected)\n        print(\"IPv4:\", session.active_ipv4_prefix)\n        print(\"IPv6:\", session.active_ipv6_prefix)\n        print(\"LFC:\", session.service.lfc)\n\nasyncio.run(main())\n```\n\nOr omit `api_key` and set the environment variable instead:\n\n```bash\nexport QUICNZ_API_KEY=\"YOUR_API_KEY\"\n```\n\n```python\nasync with QuicClient() as client:\n    ...\n```\n\n## Reusing an aiohttp session\n\nIf your application already manages an `aiohttp.ClientSession` you can pass it\nin to avoid creating an extra connection pool:\n\n```python\nimport aiohttp\nfrom quicnz import QuicClient\n\nasync with aiohttp.ClientSession() as http_session:\n    client = QuicClient(api_key=\"YOUR_API_KEY\", session=http_session)\n    session = await client.get_session(\"service123\")\n```\n\n## API reference\n\n### `QuicClient(api_key=None, *, session=None)`\n\nMain entry point.  Use as an async context manager or pass an existing\n`aiohttp.ClientSession`.  If `api_key` is omitted, the `QUICNZ_API_KEY`\nenvironment variable is used.  A `ValueError` is raised if neither is provided.\n\n| Method | Returns | Description |\n|---|---|---|\n| `get_services()` | `list[str]` | Service IDs authorised for this API key |\n| `get_session(service_id)` | `Session` | Active session for a service |\n| `get_weathermap(source=\"website\")` | `bytes` | Weather map image bytes (website or API source) |\n\n### `Session`\n\n| Attribute | Type | Description |\n|---|---|---|\n| `status` | `str` | e.g. `\"connected\"` |\n| `is_connected` | `bool` | `True` when `status == \"connected\"` |\n| `session_type` | `str` | `\"DHCP\"` or `\"PPPoE\"` |\n| `active_ipv4_prefix` | `str` | Assigned IPv4 address |\n| `active_ipv4_prefix_length` | `int` | IPv4 prefix length |\n| `active_ipv6_prefix` | `str` | Assigned IPv6 prefix |\n| `active_ipv6_prefix_length` | `int` | IPv6 prefix length |\n| `last_radius_update` | `datetime` | Last RADIUS accounting update |\n| `session_expires_at` | `datetime` | When the session expires |\n| `ppp_payload` | `PPPPayload \\| None` | PPPoE session details (PPPoE only) |\n| `service` | `ServiceInfo` | Static service configuration |\n| `created_at` | `datetime` | |\n| `updated_at` | `datetime` | |\n\n### `ServiceInfo`\n\n| Attribute | Type | Description |\n|---|---|---|\n| `username` | `str` | PPPoE/DHCP username |\n| `lfc` | `str` | Local Fibre Company (e.g. `\"Chorus\"`) |\n| `status` | `str` | Service status (e.g. `\"active\"`) |\n| `asid` | `str` | AS identifier |\n| `datacap` | `float` | Data cap (0 = uncapped) |\n| `static_ipv4_prefix` | `str` | Static IPv4 prefix (if any) |\n| `static_ipv6_prefix` | `str` | Static IPv6 prefix (if any) |\n| `routes` | `list[str]` | Announced routes |\n\n### Exceptions\n\n| Exception | When raised |\n|---|---|\n| `QuicAuthError` | HTTP 403 – invalid or missing API key |\n| `QuicNotFoundError` | HTTP 404 – resource not found |\n| `QuicAPIError` | Any other HTTP error; has `.status: int` attribute |\n| `QuicError` | Base class for all quicnz exceptions |\n\n## Rate limits\n\nThe Quic API enforces a limit of **120 requests per minute**.  Session data is\ncached server-side for 5 minutes; the weather map is cached for 6 minutes.\n\nThe default weather map source is the website endpoint. Use the API endpoint explicitly if preferred:\n\n```python\nimage = await client.get_weathermap(source=\"api\")\n```\n\n## Development\n\n```bash\n# Clone and install in editable mode with dev extras\ngit clone https://github.com/ageron/quicnz\ncd quicnz\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Lint / type-check\nruff check src tests\nmypy src\n```\n\n## Licence\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fageron%2Fquicnz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fageron%2Fquicnz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fageron%2Fquicnz/lists"}