Wattworx API v1

Welcome to the Het Wattworx API service. This document provides detailed information about the available API endpoints, parameters, and response formats.

Authentication
Response Formats
Device List
Device Types
Device Authorisation Status
Month Values
Day Values
Day Detail Values
Metering Time Format
Add EAN
Delete EAN
Client Overview
Add Client
Delete Client
Day Data Request

Authentication

To access the Wattworx API, you need an API key. Here's how to get started:

Getting Your API Key

Log in to your Wattworx account.
Navigate to the API Tokens page in your user profile.
Create a new token and copy it to a safe location.

Using Your API Key

You can use your API key in two ways:

Option 1: In the URL

Include your key directly in the URL by adding /key/YOUR_KEY:

https://wattworx.nl/api/v1/ean/list/key/YOUR_KEY

Option 2: As a Bearer Token

Add your key to the Authorization header:

Authorization: Bearer YOUR_KEY

Replace YOUR_KEY with the token you generated in your account.

Important

Keep your API key secure and never share it publicly
Each key is personal to your account
You can create, view, and delete keys anytime from the API Tokens page

Response Formats

You can specify the response format for any API request by appending one of the following to the request URL. The default format is XML.

.../format/xml
.../format/json
.../format/csv

Device List

Retrieves all devices associated with your API key. For multi-client keys, it returns all devices the key has access to across all clients.

Endpoint: ../api/v1/ean/list

URL: https://wattworx.nl/api/v1/ean/list/key/YOUR_KEY

Optional Parameters

Device Code: Retrieve a specific device.
- .../code/EAN_CODE
Client ID: Filter devices by a specific client. CLIENT_ID is obtained from the ../client/list endpoint.
- .../client/CLIENT_ID
Active Status: Filter devices based on their activity.
- .../active/true (for active devices)
- .../active/false (for inactive devices)

Example Response

<device>
    <id>9998</id>
    <ean>871234567890123456</ean>
    <eantype>KVBE</eantype>
    <meterId>BC233232j44444</meterId>
    <address>STADSTRAAT 111</address>
    <zip>9999AA</zip>
    <city>GRONINGEN</city>
    <rnb>Liander NWN</rnb>
    <laststatus>Intervalstanden van 10-09-2013 gepubliceerd</laststatus>
    <client>
        <id>1111</id>
        <name>Klant 1</name>
        <kvk>1234567890</kvk>
        <authorisation>MA00222</authorisation>
        <authorisationstatus>Getekend</authorisationstatus>
        <firstDataDate>2013-07-12</firstDataDate>
        <lastDataDate>2013-09-10</lastDataDate>
    </client>
</device>

Device Types

Lists all available device types.

Endpoint: ../api/v1/ean/eantype

URL: https://wattworx.nl/api/v1/ean/eantype/key/YOUR_KEY

Device Authorisation Status

Lists all possible device authorisation statuses.

Endpoint: ../api/v1/ean/authorisationstatus

URL: https://wattworx.nl/api/v1/ean/authorisationstatus/key/YOUR_KEY

Month Values

Retrieves monthly readings for a device, specified by either its ID or EAN code.

Endpoint: ../api/v1/ean/monthvalues/..

URL:

https://wattworx.nl/api/v1/ean/monthvalues/id/DEVICE_ID/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/monthvalues/code/EAN_CODE/key/YOUR_KEY

Optional Parameters

Date Range: Specify a period using YYYYMMDD format. If omitted, returns data for the last 12 months.
- .../start/START_DATE/end/END_DATE
- .../start/START_DATE
- .../end/END_DATE

Example Responses

KVBE EAN Type:

<month>
    <year>2013</year>
    <month>11</month>
    <kwhConsReading>5901.0</kwhConsReading>
    <kwhConsLowReading>825.0</kwhConsLowReading>
    <kwhProdReading>0</kwhProdReading>
    <kwhProdLowReading>0</kwhProdLowReading>
</month>

GVBG EAN Type:

<month>
    <year>2013</year>
    <month>11</month>
    <m3ConsReading>1123.1</m3hConsReading>
</month>

Day Values

Retrieves daily readings for a device.

Endpoint: ../api/v1/ean/dayvalues/..

URL:

https://wattworx.nl/api/v1/ean/dayvalues/id/DEVICE_ID/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/dayvalues/code/EAN_CODE/key/YOUR_KEY

Optional Parameters

Date Range: Specify a period using YYYYMMDD format. If omitted, returns data for the last 30 days.
- .../start/START_DATE/end/END_DATE

Example Response

<day>
    <date>2013-12-22</date>
    <kwhConsReading>5901.0</kwhConsReading>
    <kwhConsLowReading>825.0</kwhConsLowReading>
    <kwhProdReading>0</kwhProdReading>
    <kwhProdLowReading>0</kwhProdLowReading>
</day>

Day Detail Values

Retrieves detailed interval readings for a specified date range. By default, returns the last 7 days of data when no dates are specified. The maximum date range is 60 days.

Endpoint: ../api/v1/ean/innerdayvalues/..

URL Examples:

https://wattworx.nl/api/v1/ean/innerdayvalues/id/DEVICE_ID/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/innerdayvalues/code/EAN_CODE/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/innerdayvalues/code/EAN_CODE/date/YYYYMMDD/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/innerdayvalues/code/EAN_CODE/start/YYYYMMDD/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/innerdayvalues/code/EAN_CODE/end/YYYYMMDD/key/YOUR_KEY
https://wattworx.nl/api/v1/ean/innerdayvalues/code/EAN_CODE/start/YYYYMMDD/end/YYYYMMDD/key/YOUR_KEY

Optional Parameters

Date Range: Specify a period using YYYYMMDD format:
- date (legacy): Returns data for a single specific day (e.g., /date/20250209)
- start and end: Returns data between start and end dates, inclusive (max 60 days apart)
- start only: Returns 7 days of data starting from the start date (inclusive)
- end only: Returns 7 days of data ending on the end date (inclusive)
- No date parameters: Returns the last 7 complete days (excluding today)
Note: The date parameter cannot be combined with start or end parameters.
Time Format (tf): See Metering Time Format for options.
Values (values): Controls the unit and format of readings for KV electricity devices (KVBE). Does not affect gas or GV devices.
- .../values/WH — Returns readings in Wh (watt-hours) with high/low tariff split. This is the original format.
- .../values/KWH — Returns readings divided by 1000 (kWh) without low tariff values, and includes a consumption/production diff between consecutive readings.
- Default: WH until 2026-03-08T23:00:00, then KWH becomes the default.

Example Responses

KVBE with values=WH (default before 2026-03-08T23:00:00):

<daydetail>
    <datetime>2013-01-14 23:45:00</datetime>
    <kwhConsLowReading>0</kwhConsLowReading>
    <kwhConsReading>5901.0</kwhConsReading>
    <kwhProdLowReading>0</kwhProdLowReading>
    <kwhProdReading>825.0</kwhProdReading>
</daydetail>

KVBE with values=KWH (default after 2026-03-08T23:00:00):

<daydetail>
    <datetime>2013-01-14 23:45:00</datetime>
    <kwhConsReading>5.901</kwhConsReading>
    <kwhProdReading>0</kwhProdReading>
    <kwhCons>0.2</kwhCons>
    <kwhProd>0</kwhProd>
</daydetail>

KVBG (gas) — unaffected by values parameter:

<daydetail>
    <timestamp>1358203500</timestamp>
    <m3ConsReading>5874.644</m3ConsReading>
</daydetail>

Metering Time Format

You can specify the time format for day detail values using the tf parameter.

1: Dutch Timezone (Winter: CET, Summer: CEST) [DEFAULT] (Example: 2013-01-14 23:45:00)
2: CET Timezone (Example: 2013-01-14T23:45:00+01:00)
3: Unix Timestamp (Example: 1358203500)
4: UTC Timezone (Example: 2013-01-14 22:45:00)

Example (tf=4):

<daydetail>
    <datetime>2013-01-14 22:45:00</datetime>
    <kwhCons>3.1832</kwhCons>
    <kwhConsReading>2131.7592</kwhConsReading>
</daydetail>

Add EAN

Adds an EAN to an existing client.

Endpoint: ../api/v1/ean/add/..

URL: https://wattworx.nl/api/v1/ean/add/client/CLIENT_ID/code/EAN_CODE/eantype/EAN_TYPE/key/YOUR_KEY

Required Parameters

meterid: Required for KVBE or KVBG eantypes. Provide the last 8 numeric digits of the smart meter number. Use paper to skip validation and upload a signed authorisation manually.
- .../meterid/METER_ID

Optional Parameters

Address Details:
- .../zip/ZIP_CODE
- .../streetnumber/STREETNUMBER
- .../extension/EXTENSION
start: Set a specific start date for data readings (YYYYMMDD).
- .../start/START_DATE

Example Response

<ean>
  <id>1234</id>
  <code>973266366322233112</code>
  <authorisationstatus>Validatie in behandeling</authorisationstatus>
</ean>

Delete EAN

Deletes an EAN from a client.

Endpoint: ../api/v1/ean/delete/..

URL: https://wattworx.nl/api/v1/ean/delete/client/CLIENT_ID/code/EAN_CODE/key/YOUR_KEY

Example Response

<ean>
  <id>1234</id>
  <code>973266366322233112</code>
  <status>Verwijderd</status>
</ean>

Client Overview

Retrieves a list of all clients in your account.

Endpoint: ../api/v1/client/list

URL: https://wattworx.nl/api/v1/client/list/key/YOUR_KEY

Example Response

<clients>
  <client>
    <id>999</id>
    <name>Klant BV</name>
    <kvk>1234567890</kvk>
    <address>Voorbeeldweg 58</address>
    <zip>1111AA</zip>
    <city>Amsterdam</city>
    <authorisations>
      <authorisation>
        <number>MA9999</number>
        <status>Getekend</status>
        <eans>
          <ean>871234567891234567</ean>
        </eans>
      </authorisation>
    </authorisations>
  </client>
</clients>

Add Client

Adds a new client to your account. Client details should be URL-encoded.

Endpoint: ../api/v1/client/add/..

URL: https://wattworx.nl/api/v1/client/add/name/CLIENT_NAME/address/ADDRESS/zip/ZIP_CODE/city/CITY/key/YOUR_KEY

Optional Parameters

kvk: KVK number.
contactname: Contact person's name.
contactemail: Contact person's email.
signname: Authorised signatory's name.
signposition: Authorised signatory's position.

Example Response

<client>
  <id>9999</id>
  <name>Klant BV</name>
  <address>Dorpsstraat 1</address>
  <zip>1234AA</zip>
  <city>Amsterdam</city>
</client>

Delete Client

Deletes a client from your account.

Endpoint: ../api/v1/client/delete/..

URL: https://wattworx.nl/api/v1/client/delete/id/CLIENT_ID/key/YOUR_KEY

Example Response

<client>
  <id>9999</id>
  <name>Klant BV</name>
  <status>Removed</status>
</client>

Day Data Request

Requests data for a specific day for a KVBE or KVBG EAN. The request can be for a maximum of 30 days in the past, but future dates are also allowed.

Endpoint: ../api/v1/ean/requestdayvalues/..

URL: https://wattworx.nl/api/v1/ean/requestdayvalues/code/EAN_CODE/date/YYYYMMDD/key/YOUR_KEY

Example Response

If the request is queued:

<ean>
  <id>9999</id>
  <eanCode>871234567890123456</id>
  <status>Dayrequest for 2017-01-01 queued</status>
</ean>

If the data is already available, the response will be the same as the Day Values endpoint.

Wattworx API v1

Table of Contents

Authentication

Getting Your API Key

Using Your API Key

Important

Response Formats

Device List

Optional Parameters

Example Response

Device Types

Device Authorisation Status

Month Values

Optional Parameters

Example Responses

Day Values

Optional Parameters

Example Response

Day Detail Values

Optional Parameters

Example Responses

Metering Time Format

Add EAN

Required Parameters

Optional Parameters

Example Response

Delete EAN

Example Response

Client Overview

Example Response

Add Client

Optional Parameters

Example Response

Delete Client

Example Response

Day Data Request

Example Response