gaggle

Home Assistant custom integration that pulls smart-meter gas usage from AGL Australia and feeds it into the HA Energy dashboard.

Unofficial community integration. Not affiliated with, endorsed by, or supported by AGL Energy Limited. The API contract used by this integration is not publicly documented and may change at any time; any breakage will be addressed on a best-effort basis.

Australia only. Requires an AGL Energy gas account.

Status: pre-release, functional against a basic (non-smart) gas meter. gaggle is a sibling project to haggle (which does the same thing for AGL electricity). Auth, contract discovery, real gas usage data, and statistics import all work, confirmed against a real AGL account. The confirmed shape turned out to differ from electricity in an important way: a basic gas meter has no interval/daily data at all — AGL only exposes a current-period estimate plus a window of already-billed past periods. So the Energy dashboard gets one bar per completed billing period (roughly every two months), not a smooth daily chart. See docs/gas-api.md for the full findings. No release has shipped yet — see docs/releasing.md.

Why

AGL is one of Australia's largest gas retailers. gaggle uses the same authenticated API their mobile app uses to fetch your gas usage and feed it into Home Assistant's long-term statistics, the way haggle already does for electricity.

Install

Not yet published to HACS. Install as a HACS custom repository:

1. HACS → ⋮ → Custom repositories → add this repo URL as an Integration.
2. Settings → Devices & Services → Add integration → search AGL Gaggle.
3. A login URL is shown. Open it in your real browser (handles Akamai bot-protection and MFA transparently). Complete your AGL login.
4. After login, AGL redirects to a "Not Found" page. Copy the full URL from your browser's address bar and paste it into the HA dialog.
5. If you have multiple gas contracts, select the one to monitor.

The integration polls once per day. Your current billing period's usage and cost sensors update on that cadence with AGL's own estimate; the Energy dashboard statistic gains a new bar each time a billing period completes (bimonthly for most plans).

Removing

Delete the Gaggle entry from Settings → Devices & Services. On removal the integration makes a best-effort call to AGL's sign-in service (Auth0) to revoke its stored refresh token, so the grant does not outlive the install. Your imported gaggle:* statistics are deliberately kept; prune them via Developer Tools → Statistics if you want them gone.

Energy dashboard

Add the gaggle:consumption_<contract> statistic as your dashboard's Gas consumption source — never the sensor.… entities. Expect a sparse chart: one bar per completed billing period, not daily bars — there's no underlying interval data for a basic gas meter to build a smoother chart from.

Full setup guide and troubleshooting: docs/energy-dashboard.md.

Develop

See AGENTS.md for the full dev workflow and AGL API contract documentation. See docs/gas-api.md for the confirmed API findings and what's still open (support for smart-metered gas accounts).

Provenance

This codebase is generated by Claude Code and reviewed by a human. Ported from haggle commit 04ebc21b53315ec9b176b71c2abfbe69d80ce8d7.

License

Apache-2.0 — see LICENSE.