Integrating a data collection system

  • Updated

If you are the provider of a data collection system such as a Gateway, DUC, or even a cloud-based solution, it is possible for you to upload data to Metry for your customers. This can provide numerous benefits for your customers.

  • It enables the consolidation of all of their data collection on a single platform.
  • The data can be used in energy management systems already integrated with Metry. 
  • Metry provides additional processing and quality assurance of the data.

Authentication

To start uploading data, you need to first create a feed. This requires that your request is authenticated using either the user's private access token or with an access token acquired using OAuth. These tokens don't have permissions to create feeds by default, so contact support@metry.io to enable this.

The requests to upload data require a different token which is created specifically for the feed you created.

Create a feed

To upload data to Metry, a feed is required which holds configurations for how to parse and process the data. This gives the user an understanding of where data is coming from.

To create a feed, use the request below. The name of the feed will be visible for the user in Metry, so it should preferably be descriptive such as being the name of the system uploading data so that the user knows where the data is coming from.

POST https://app.metry.io/api/v2/feeds

{
    "name": "My Submetering system",
    "format": {
        "parser": "Document\\Metry\\ReadingsJSON",
        "params": {
            "expected_granularity": "hour"
        }
    },
    "protocol": {
        "http": {}
    }
}

This will return the following response. A unique token is automatically generated which should be used to upload data. Get the token from the response at data.protocol.http.token. The token used for authenticating to create this feed can not be used to upload data later. The token created in this process has more restricted access and can only be used to upload data for this specific feed. 

{
    "code": 200,
    "data": {
        "_id": "5cb579991976580080499454",
        "holder": {
            "_id": "540da71a2c3d1c3c008b5368",
            "name": "Customer",
            "username": null
        },
        "provider": {
            "_id": null,
            "name": null,
            "username": null
        },
        "name": "My Submetering system",
        "overwrite": true,
        "active": true,
        "format": {
            "parser": "Document\\Metry\\ReadingsJSON",
            "params": {
                "expected_granularity": "hour"
            }
        },
        "protocol": {
            "ftp": null,
            "smtp": null,
            "http": {
                "token": "f997a41183bf39100584881edf7a079fb9650639"
            },
            "ediel": null,
            "robot": null
        },
        "protocols": ["http"]
    }
}

 

Upload data for a feed

Using the token stored on the feed that was created in the previous step, it is now possible to upload readings or consumption values. The data format used to upload depends on the format specified when creating the feed. The format created in the example above expects a JSON array with objects with the following fields.

  • id – A unique ID for the meter.
  • date – A date for when the reading was made in ISO 8061 format with specified timezone offset.
  • value – The meter’s reading value.
  • unit – Either kWh, MWh, m3, or C.
  • type – Either electricity, heat, cooling, water, hot_water, or sensor.

Optional fields

  • name – A name of the metering point that will be visible for the user in Metry.

The request requires the token that is set on the feed created before and must be passed as a query parameter in the URL.

 

POST https://app.metry.io/hooks/http?token=ADD_TOKEN_HERE
[{
    "id": "82736582", 
    "date": "2019-04-16T07:53:04+00:00", 
    "value": 327189, 
    "unit": "kWh", 
    "type": "electricity"
}, {
    "id": "235235", 
    "date": "2019-04-16T07:53:04+00:00", 
    "value": 513.532, 
    "unit": "m3",
    "type": "water"
}]

 

Related articles