How to use the water meter API

Use the Smart Meter Solutions API suite to programmatically obtain water meter readings to facilitate invoicing. This functionality is intended for use by customer or third party developers looking to automate processes requiring water meter readings.

Prerequisites

• Digital Water Management Plan OR Smart Meter Solutions Addon
• You will need to request an API Key to obtain meter readings from live meters.
• A list of Meter IDs for which you wish to obtain meter level readings, typically provided by your water utility partner

It is helpful to have domain-specific knowledge regarding the information recorded by water meters and the frequency with which they meter level readings, consumption, and any alarm conditions.

Terminology

MeterLevel - Meter reading in units of m³. This is the lifetime value of the meter consumption, not the daily/weekly/monthly consumption.

MeterID - A meter identification for which you wish to retrieve a meterLevel reading.

TimestampLast - A historical timestamp that represents the latest point for which to retrieve meter level readings. Retuned readings will never be after this timestamp. Value must be in the past. If omitted, timeStampLast will be set to the time of query execution (latest available).

Creating a developer account and subscribing to the API.

1. Create an account at https://developer.klinkplatform.com/signup.
2. After your account has been approved, sign in and subscribe to the Smart Meter Solutions API.
   1. You can name the subscription in a manner that suits your purposes. Please include the municipality name.
   2. We suggest creating a Dev/Test subscription first. This will then be connected to a demo data set for you to test.
   3. Once you are comfortable with the API, you can subscribe to live meters. This will need to be approved by the municipality.
3. The subscriptions are reviewed and activated within 1 business day.

Testing the API 

1. Once approved, you will be able to sign back into your account and use the API. (direct link)
   1. Click 'Try It'
2. Under Authorization, select the Primary Subscription Key for the subscription you created earlier.
3. Leave MeterID and TimestampLast blank
4. Click Send
5. You should see a response.

Requesting specific meters / dates

You can request specific meters and or dates.

1. Enter a meterID from the list of meter IDs provided by your water utility partner.
   • Multiple ID's can be seperated by commas.
   • For the Dev/test data set, try 00E944879217D22D,0930BCE323B9EF90
2. TimeStampLast may be left blank to retreive the latest available data. 
   • A specific time (eg end of the month) can be passed using rfc3339 format yyyy-MM-ddTHH:mm:ss+00:00
   • For the Dev/test data set, try 2022-01-18T22:38:56+00:00
3. Press Send

You should receive a 200 response along with the meter level for the meter Id you requested. The timestamp for the reading is also provided.

Example request
meterID: 00E944879217D22D,0930BCE323B9EF90

TimestampLast: 2022-01-18T22:38:56+00:00

Example Response

HTTP/1.1 200 OK

content-length: 195
content-type: application/json; charset=utf-8
date: Mon, 25 Apr 2022 09:26:35 GMT
vary: Origin

[{
    "meterId": "00E944879217D22D",
    "timestamp": "2022-01-18T11:33:56+00:00",
    "meterLevel": 14.526300000000008
}, {
    "meterId": "0930BCE323B9EF90",
    "timestamp": "2022-01-18T14:37:21+00:00",
    "meterLevel": 67.302
}]

Instructions for Integrating the API to your application

Using the API programmatically is beyond the scope of this article. It is assumed that software engineers will be able to use the swagger documentation provided on the Smart Meter Solutions API page to build their integration to InfoTiles.

If specifying individual meters, it is recommended to batch requests to the invoicing API in batches of 150 meterIDs to remain within an URL length of 2000 characters.

Further support can be requested by submitting a support request.

Outcome

Completing these steps will allow the user to verify that they have the requisite access and inputs to use the InfoTiles invoicing API.

Further reading

What is REST - REST API Tutorial (restfulapi.net)