Partner API documentation

Admin interface

You are able to explore your organisation’s Powerpals via the device admin service. Note that this is our internal admin backend for our own data visualisation purposes and the UI is not intended for our core retail household users in its present form.

Powerpal’s backend uses Google accounts for authentication. If your organisation does not use GSuite we recommend creating a dedicated Gmail account and requesting access via support@powerpal.net.

Powerpal meter readings API

API host

https://readings.powerpal.net

Data structure

The Powerpal hardware logs energy usage data at 60 second intervals. This is available as a time series of five columns:

timestamp A unix timestamp (number of seconds since 1970). Generally a continuous time series but this is not guaranteed and should not be relied upon.
watt_hours The amount of energy consumed in this 60 second period. Powerpal only measures draw from the grid – if the household has solar panels the recorded usage will be lower than their total usage and may be zero on sunny days. 99.99% accurate to the regulated meter data.
cost The dollar cost to the household of this period as displayed to the user in the Powerpal app based on their parsed recent electricity bill. Includes GST and pro-rated daily supply charge. Should be treated as an approximation as users’ tariffs may be outdated and not all forms of discount (e.g. pay-on-time) are accounted for.
is_peak Indicates if this period fell within a peak cost window for users on time-of-use tariffs. For distributors with a triple peak/off-peak/shoulder structure, both off-peak and shoulder periods will be false.
pulses The number of LED flashes recorded by the Powerpal photosensor in this period. May be combined with watt_hours to infer the pulses/KWh of the household’s electricity meter. Meters with a low pulses/KWh are “lower resolution” and their data may appear spikier than high resolution meters.

Data availability

The Powerpal hardware records usage at the electricity meter every 60 seconds. When the user’s mobile phone is within range, this data will be broadcast to the Powerpal servers every 15 minutes and will be immediately available through the API.

This 15 minute batching exists to optimise battery life for the user’s mobile phone and may be remotely increased to true real-time 60 second updates in periods of particular interest.

While the user is out of bluetooth range their Powerpal device will buffer readings for 3 months. As soon as the user returns home their full history will be downloaded from their Powerpal and sent to the Powerpal servers.

API access

Meter reading data may be accessed over a RESTful HTTP API and is generally available in JSON format. While the examples in this document use curl you will be easily able to translate the principles into the programming language of your choice.

Access is authenticated by the presence of your Powerpal admin account’s API key in the HTTP Authorization header. You will find your own API key in the device admin service.

Individual Powerpal devices are addressed by their unique 8 character hexadecimal serial number as printed on the base of the hardware (e.g. 1a2b3c4d ).

Meter reading time series

GET /api/v1/meter_reading/<serial_number>

Provides 60 second interval time series data as described above for a single device. Limited to 50,000 records per request (about one month of readings at 60 second sampling).

start and end parameters may be provided as unix timestamps to specify a time range. This may be used repeatedly to script access to large-scale historical data. If start and end are omitted, readings from the past 24 hours will be returned. Note that this may be an empty list if the Powerpal has not been online recently.

The optional sample parameter (integer minutes) will “bucket” the readings into larger time periods. Providing sample=60 will bucket readings into hours (i.e. 24 records per day).

Request

curl -H "Authorization: <MY_API_KEY>" https://readings.powerpal.net/api/v1/meter_reading/abcd0001?start=1530367200\&end=1533045600\&sample=10

Response
[
  {
    "timestamp": 1533045600,
    "pulses": 13,
    "watt_hours": 13,
    "cost": 0.01398161,
    "is_peak": false
  },
  {
    "timestamp": 1533045000,
    "pulses": 7,
    "watt_hours": 7,
    "cost": 0.01193561,
    "is_peak": false
  },
  ...
]

 

CSV request

This endpoint can also provide the response in CSV format for the convenience of those who like to experiment in Excel by providing the Accept: text/csv header:

curl -H "Authorization: <MY_API_KEY>" -H "Accept: text/csv" https://readings.powerpal.net/api/v1/meter_reading/abcd0001 > powerpal_data.csv

Compressed responses

50,000 readings in JSON format is roughly a 4MB response. You can significantly reduce the download size and speed up your scripts by setting the Accept-Encoding: gzip header to enable GZip compression, reducing the download to 150KB (a 27x reduction).

You may find that your HTTP client already does this for you and handles decompression transparently. If you prefer to use something lower level like curl you must set the additional header and pipe the compressed response through gunzip to retrieve the readable data.

curl -H "Authorization: <MY_API_KEY>" -H "Accept-Encoding: gzip" https://readings.powerpal.net/api/v1/meter_reading/abcd0001 | gunzip > powerpal_data.json

Powerpal device information API

API host

https://devices.powerpal.net

List Powerpal devices

GET /api/v1/energy_bridges

Provides a list of all Powerpal devices accessible by your organisation.

This endpoint is paginated. To access more than the most recent 200 Powerpal devices you may provide page=N parameter. When page N contains no further devices the list will be empty.

To support polling for new devices the optional since parameter may be provided as a as unix timestamp to filter the list to devices with a factory_timestamp more recent than the parameter.

NB: pulses_per_kwh, led_sensitivity, os, os_version and app_version are recently added fields which may not be present for early beta devices.

Request

curl -H "Authorization: <MY_API_KEY>" https://devices.powerpal.net/api/v1/energy_bridges?since=1546261200&page=2

Response
{
  "page": 2,
  "energy_bridges": [
    {
      "serial_number": "abcd0001",
      "factory_timestamp": 1550811338,
      "postcode": "3100",
      "state": "VIC",
      "pairing_code": "123456",
      "pulses_per_kwh": 1000,
      "led_sensitivity": 9,
      "os": "ios",
      "os_version": "12",
      "app_version": "1.3.0"
    },
  ...
  ]
}

 

Get single Powerpal device

GET /api/v1/energy_bridges/<serial_number>

Provides information a single Powerpal device in the same format as “List Powerpal devices”.

Request

curl -H "Authorization: <MY_API_KEY>" https://devices.powerpal.net/api/v1/energy_bridges/abcd001

Response
{
  "serial_number": "abcd0001",
  "factory_timestamp": 1550811338,
  "postcode": "3100",
  "state": "VIC",
  "pairing_code": "123456",
  "pulses_per_kwh": 1000,
  "led_sensitivity": 9,
  "os": "ios",
  "os_version": "12",
  "app_version": "1.3.0"
}

 

Get current tariff for a Powerpal device

GET /api/v1/tariffs?serial_number=<serial_number>

Provides the most recent tariff information for a given Powerpal device. This may have been parsed from a PDF electricity bill or manually entered by the mobile app user.

Request

curl -H "Authorization: <MY_API_KEY>" https://devices.powerpal.net/api/v1/tariffs?serial_number=abcd001

Response
{
  "state": "VIC",
  "postcode": "3100",
  "distributor_code": "AUSGRID",
  "distributor_name": "Ausgrid",
  "retailer_code": "ORIGIN",
  "retailer_name": "Origin Energy",
  "supply_charge_cost_per_day": 1.94953,
  "rates": [
    {
      "name": "Peak",
      "cost_per_kwh": 0.49324,
      "weekday": [
        {
          "start": "14:00",
          "end": "20:00"
        }
      ],
      "weekend": []
    },
    {
      "name": "Shoulder",
      "cost_per_kwh": 0.22671,
      "weekday": [
        {
          "start": "07:00",
          "end": "14:00"
        },
        {
          "start": "20:00",
          "end": "22:00"
        }
      ],
      "weekend": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    {
      "name": "Off-peak",
      "cost_per_kwh": 0.15147,
      "weekday": [],
      "weekend": []
    }
  ],
  "discount_percent": 15,
  "discount_applies_to_supply_charge": false
}

 

Other available data

In addition to the usage data as described above Powerpal can also provide anonymised metadata about the location, distributor, retailer and pricing tariff associated with each Powerpal household. We’re always happy to discuss your requirements and work with your technology business to incorporate access to these additional data sources.

In early 2019 new APIs will become available combining these and other data sources to providing intelligent insights beyond the raw meter readings available today.

The Powerpal app provides a two-way messaging channel to let the user put this intelligence to work for them and help them to make better decisions about the way they use energy in the future.

Alternative data access approaches

The API as documented has primarily been built to fulfil the needs of the Powerpal app. Powerpal’s backend infrastructure has been designed from the ground up for large-scale data management and providing partners with alternative access technologies is extremely viable, be it via regular dumps of ingestable data files or a push subscription to real-time meter readings data.

To discuss your requirements please get in touch!