A custom Home Assistant integration that provides energy usage, cost, billing, and 15-minute AMI meter data from National Grid utility accounts. It uses the py-nationalgrid library to communicate with National Grid's API.
This is a fork of ryanmorash/ha_nationalgrid, updated to use the actively maintained py-nationalgrid library and rebuilt around the 15-minute AMI data endpoint.
- Account & Meter Device Hierarchy: Account devices appear as parent devices in HA; each meter device is linked via "Connected via" to its account
- Energy Usage & Cost Sensors: Monthly billing usage and costs for electric and gas meters
- Current Bill Sensor: Current billing period charges with due date, statement date, and status as attributes
- Next Reading Date: Diagnostic sensor showing the next scheduled meter read date per account
- Smart Meter Detection: Identifies meters with AMI (Advanced Metering Infrastructure) capabilities
- 15-Minute AMI Statistics: Imports granular energy data into Home Assistant's Energy Dashboard
- Solar / Return Support: Separate statistics for grid consumption and energy returned to the grid
- Historical Data Import: On first setup, imports all available AMI data (as far back as National Grid retains for your meter)
- Fast Restarts: After the initial import, HA restarts skip the historical fetch and load in seconds
- Per-Meter Force Refresh: Button entity on each meter device to re-import its full history on demand
- Force Refresh Service: Manually trigger a full historical data refresh for all meters
- Reconfigure Support: Change your monitored account selection at any time without re-entering credentials
- Diagnostics: Full support for HA's "Download Diagnostics" with all sensitive data redacted
Migrating from the original integration? Uninstall
ryanmorash/ha_nationalgridfrom HACS and remove the integration entry from Settings > Devices & Services before installing this one. Both use the same domain (national_grid), so they cannot coexist.
Upgrading from an earlier version of this fork? Statistics IDs now include the account ID prefix (e.g.,
national_grid_us:1234567890_SP001_electric_hourly_usage). If you had the old format (national_grid_us:SP001_electric_hourly_usage) configured in the Energy Dashboard, you will need to update those references after upgrading. See Long-Term Statistics for the new format.
- Open HACS in your Home Assistant instance.
- Go to Integrations and select the three-dot menu in the top right corner.
- Select Custom repositories.
- Add the URL
https://github.com/virtitnerd/ha_nationalgridwith category Integration. - Find National Grid in the HACS integration list and click Download.
- Restart Home Assistant.
- Download the
custom_components/national_grid_usfolder from this repository. - Copy the
national_grid_usfolder into your Home Assistantconfig/custom_components/directory. - Restart Home Assistant.
Configuration is done entirely through the Home Assistant UI.
- Go to Settings > Devices & Services > Add Integration.
- Search for National Grid.
- Enter your National Grid account username and password.
- Select which billing accounts to monitor from the list of accounts linked to your login.
To change which accounts are monitored after initial setup:
- Go to Settings > Devices & Services.
- Find the National Grid integration entry.
- Click the three-dot menu and select Reconfigure.
- Select or deselect accounts as needed.
| Parameter | Description |
|---|---|
| Username | Your National Grid online account email or username |
| Password | Your National Grid online account password |
| Selected Accounts | Which linked billing accounts to monitor |
- Go to Settings > Devices & Services.
- Find the National Grid integration entry.
- Click the three-dot menu and select Delete.
- Optionally, remove the
custom_components/national_grid_usfolder and restart Home Assistant.
The integration uses a two-level device hierarchy:
National Grid {account_id} ← Account device (one per billing account)
├── sensor: Current Bill
├── sensor: Next Reading Date
└── Electric Meter {account_id}-{sp} ← Meter device (one per service point)
├── sensor: Last Billing Usage
├── sensor: Last Billing Cost
├── sensor: Avg Cost per Unit
├── binary_sensor: Smart Meter
└── button: Force Refresh
These sensors live on the account device and reflect account-level data.
| Entity | Description | Unit | Device Class | Category |
|---|---|---|---|---|
| Current Bill | Current billing period charges | USD | Monetary | — |
| Next Reading Date | Next scheduled meter read date for this account | — | Date | Diagnostic |
Current Bill attributes:
| Attribute | Description |
|---|---|
due_date |
Payment due date |
statement_date |
Date the bill was issued |
status |
Bill status (e.g., PAID, UNPAID) |
total_due |
Total amount due including any prior balance |
| Entity | Description | Unit | Device Class |
|---|---|---|---|
| Last Billing Usage | Most recent monthly billing usage | kWh (electric) / CCF (gas) | Energy / Gas |
| Last Billing Cost | Most recent monthly billing cost | USD | Monetary |
| Avg Cost per Unit | Blended rate over the last 3 billing cycles (total cost ÷ total usage) | USD/kWh (electric) / USD/CCF (gas) | Monetary |
| Entity | Description | Category |
|---|---|---|
| Smart Meter | Whether the meter is an AMI smart meter | Diagnostic |
| Entity | Description | Category |
|---|---|---|
| Force Refresh | Re-import full AMI history for this meter on demand | Diagnostic |
Each meter device includes:
| Field | Description |
|---|---|
| Name | Fuel type + account and service point (e.g., Electric Meter 1234567890-SP001) |
| Model | Meter type (AMI Smart Meter, Smart Meter, or Standard Meter) |
| Serial Number | Meter number |
| Connected via | The parent account device |
The integration refreshes data at the 18th minute of every hour.
On first setup, the integration imports full historical data:
- All available 15-minute AMI data (as far back as National Grid retains for your meter)
- 15 months of billing usage data
- Current billing period cost data
- Bill history
This initial fetch takes 1–2 minutes per meter. Subsequent HA restarts skip this step and load in seconds.
A full data fetch including:
- Billing account information and meter details
- Energy usage records for the last 15 months
- Energy cost records for the current billing period
- Bill history
- AMI 15-minute data for the last 7 days (catches newly available and backfilled readings)
- Next scheduled reading date per account
A fast incremental fetch of near-real-time interval reads for electric meters:
- Interval reads from yesterday midnight UTC through now (REST endpoint, typically completes in under a second)
- Interval statistics are cleared and reimported on every hourly refresh so provisional data never accumulates
All readings are aggregated into hourly buckets before being stored, as required by Home Assistant's recorder.
The integration maintains two separate stat series per electric meter:
- Hourly AMI stats — verified/settled data from the AMI GraphQL endpoint. Grows permanently; only new readings are appended.
- Interval stats — near-real-time data from the REST interval endpoint, covering yesterday midnight through now. Cleared and reimported on every refresh; bridges the gap until AMI data catches up.
Statistics IDs include the account ID and service point to ensure uniqueness across accounts.
| Statistic ID | Description | Window |
|---|---|---|
national_grid_us:{account_id}_{sp}_electric_hourly_usage |
Consumption — verified AMI data (kWh) | All available history |
national_grid_us:{account_id}_{sp}_electric_return_hourly_usage |
Return to grid / solar — verified (kWh) | All available history |
national_grid_us:{account_id}_{sp}_electric_interval_usage |
Consumption — near real-time (kWh) | ~2 days |
national_grid_us:{account_id}_{sp}_electric_interval_return_usage |
Return to grid / solar — real-time (kWh) | ~2 days |
| Statistic ID | Description | Window |
|---|---|---|
national_grid_us:{account_id}_{sp}_gas_hourly_usage |
Gas consumption (CCF) | All available history |
Note:
{account_id}is your billing account number and{sp}is your meter's service point number. Both can be found in the device info for your meter in Home Assistant (e.g.,national_grid_us:1234567890_SP001_electric_hourly_usage).
Finding your IDs: Your
{account_id}and{sp}(service point number) can be found in Settings > Devices & Services > National Grid, then click your meter device and look under Device info.
- Go to Settings > Dashboards > Energy
- Under Electricity grid, click Add consumption and search for your stat ID — add each one separately:
national_grid_us:{account_id}_{sp}_electric_hourly_usage— verified AMI data (history beyond 2 days)national_grid_us:{account_id}_{sp}_electric_interval_usage— near real-time data (last ~2 days)- If you have solar/return-to-grid, also add
national_grid_us:{account_id}_{sp}_electric_return_hourly_usageunder Return to grid
- Under Gas consumption, click Add gas source and add:
national_grid_us:{account_id}_{sp}_gas_hourly_usage
Why two electricity sources? National Grid takes 1–2 days to finalize and publish verified AMI readings. The interval stat bridges that gap with near-real-time data. The integration ensures there is no overlap between them — together they give you a complete, continuous picture with no double-counting.
Triggers a full historical AMI re-import for all meters (or a specific integration entry). Equivalent to pressing the Force Refresh button on every meter device simultaneously.
Service Data:
| Field | Required | Description |
|---|---|---|
entry_id |
No | Config entry ID of a specific integration to refresh. If not provided, all National Grid integrations are refreshed. |
Example automation:
service: national_grid_us.force_full_refresh
data: {}If you notice gaps in your statistics:
- Press the Force Refresh button on the affected meter device (found under Diagnostic entities), or call the
national_grid_us.force_full_refreshservice. - Wait for completion (check logs for "Statistics import complete").
- Note: The AMI API's data availability window depends on National Grid's retention policy.
The first setup imports all available AMI history for each meter — how far back this goes depends on what National Grid retains for your specific meter. This is normal and typically takes 1–2 minutes per meter, but may take longer if the integration falls back to the 15-minute endpoint. All subsequent HA restarts complete in seconds because the initial import state is persisted.
If you upgraded from an earlier version, the statistics ID format changed to include the account ID prefix. Update your Energy Dashboard entries to the new format:
- Old:
national_grid_us:{sp}_electric_hourly_usage - New:
national_grid_us:{account_id}_{sp}_electric_hourly_usage
Enable debug logging for detailed information:
logger:
default: info
logs:
custom_components.national_grid_us: debug
py_nationalgrid: debug