Repository files navigation

This project reverse engineers theNISC SmartHubapi, which is used by hundreds of utility co-ops throughout the United States. This allowsdownloading 15-minute resolution electic usage and cost data for your personal account if you have a smart meter.

In prior versions of SmartHub, it was possible to download CSV exports of 15-minute interval usage data byspecifying an "hourly" interval, but since January 2024 only hourly data has been available via CSV. That'swhy I reverse engineered the API instead of automating a download of the CSV as I had previously done.

Data can be imported into InfluxDB or VictoriaMetrics, or exported as a CSV file.

Downloadconfig.example.yaml and fill in your own values.

• extract_days is how many days to look back from the current day. Max is 45.if specific--start and--end flags are not specified.
• account is your account number, available on your bill and on the SmartHub website.
• service_location is an internal SmartHub number, and must be retrieved from your browser:
  • Open the Developer tools to the Network tab
  • Navigate to Usage Explorer (example:https://novec.smarthub.coop/ui/#/usageExplorer)
  • Find a call toservices/secured/utility-usage/poll in the Network tab
  • Open the call, and copy theserviceLocationNumber field from the Payload tab.
• timezone needs to be set to the timezone used by your utility. For some reason,the SmartHub API decided to return unix timestamps, but in the utility's timezoneinstead of in UTC, which would be the normal choice for an API.
• influxdb section does not need to be configured if you are only using the--csv-file option.
• influxdb.insecure allows connecting to a server with certificate issues.
• The other fields should be fairly self-explanatory.

• To download and insert the lastextract_days of data, run like this arguments:electric-usage-downloader --config config.yaml
• To download and insert a specific date range, run with arguments:electric-usage-downloader --config config.yaml --start 2024-01-16 --end 2024-01-17
• The--debug flag can be used to log responses from the API for assistance debugging issues.
• The--csv-file flag will write the data to a CSV file instead of Influx/VictoriaMetrics.
  • Format: "StartUnixMillis", "EndUnixMillis", "WattHours", "CostInCents", "MeterName"
  • MeterName will only be populated if there are multiple meters returned in the data.
  • StartUnixMillis and EndUnixMillis will only be in the correct timezone if you specify the correct timezone in the config.

The SmartHub api currently supports 15-minute resolution of data. This could change in the future; 15-minute intervalusage data used to be available via CSV export, but that ability was removed in January 2024.

Measurement:electric

Fields:

• cost (in US cents)
• usage (in watts)

I have included myGrafana dashboard panel definition in the repo.

Features:

• Electric usage graphed in watts
• Trailing 1d and 7d averages
• Cumulative usage (right x axis)
• Integrated with data from my Ecobee thermostat, showing when my heat pump or aux oil heat is running.
  • Seehttps://github.com/tedpearson/ecobeemetrics for how I get this data

Here's a screenshot of the dashboard panel in action: