Skip to main content

Getting Started

This guide will help you get started with the HomeWizard Energy API.

Choosing the Right API Version​

The HomeWizard Energy API has two versions: v1 and v2. The v1 API is available as long as feasible, but will be phased out. The v2 API is the stable version and is recommended to be used. Skip to getting started with v2 if you want to use the v2 API.

Getting Started with v1​

1. Connect your Device to Wi-Fi​

Connect your Device to Wi-Fi with the HomeWizard Energy App. Make sure to connect your device with the same network as the device that makes use of the API.

2. Enable the API​

To access the data from an Energy device, you have to enable the API. You can do this in the HomeWizard Energy app. Go to Settings → Meters → Your meter, and turn on Local API.

3. Get a Measurement​

After enabling the API, you can try to read some data from your device.

  • Find the IP address of your meter. You can find this in your router or do this programmatically with mDNS.
  • In your internet browser, open http://<IP ADDRESS>/api/v1/data.
  • If everything is set up correctly, you should now see some text. This is the most recent measurement formatted as JSON. You can use a tool such as JSON Parser Online to get a structured version of the result.

To understand each value, please read endpoints.

Getting Started with v2​

In contrast to v1, the v2 API is based on HTTPS and uses authorization to access the data. This means you don't need to enable the local API in the app, but you have to obtain a token.

The following example will show you can use the API to get basic information.

1. Connect your Device to Wi-Fi​

Connect your device to Wi-Fi with the HomeWizard Energy app. Make sure to connect your device with the same network as the device that makes use of the API.

2. Get a Token​

danger

The token allows full access to the data from your device and should be kept secret. Do not share this token with others. Remove this token when you no longer need it.

  1. Get the IP address of the device.
  2. Send the following request to the device to get a token:
curl https://<IP ADDRESS>/api/user --insecure -X POST -d '{"name": "local/cool-new-app"}'
  1. You will get the following message: {"error":"user:creation-not-enabled"}.
  2. Press the button on the device once.
  3. Send the same request again to get a token:
curl https://<IP ADDRESS>/api/user --insecure -X POST -d '{"name": "local/cool-new-app"}'
  1. If everything went well, you will get a response containing a token. Store this token somewhere safe.
{
    "name": "local/cool-new-app",
    "token": "EXAMPLE-TOKEN"
}

3. Get a Measurement​

  1. Send the following request to the device to get basic information. Replace <TOKEN> with the token you received in the previous step: curl https://<IP ADDRESS>/api/measurement --insecure -H "Authorization: Bearer EXAMPLE-TOKEN"

  2. You should see a response with the the most recent data from your smart meter. Example:

{
    "power_w": 1234,
    ...
}
  1. You can use this data, and many more, to build your own application. For more information, see the v2 documentation.

Data Update Frequency​

The API always returns the most recent data. The update frequency depends on the device and, in case of the HWE-P1, the smart meter that it is connected to. With a DSMR 5.0 meter, this is every second for power and every 5 minutes for gas. If the smart meter version is lower than DSMR 5.0, this is every 10 seconds for power and every 60 minutes for gas. You can find the DSMR version of your smart meter on the smart meter itself or via the recent measurement endpoint. There is no limit to the time between each request on the local API, however, we advise not to retrieve data more often than every 500ms.