Third party access to energy data

  • Updated

This article describes how to get third party access to a Metry user's energy data. Make sure you have the following set up before you continue:

The OAuth 2 concept

Metry uses OAuth2 to grant third-party applications access end user's energy data. OAuth2 is an industry standard authorization framework that takes care of the approval interaction between the resource owner (energy user), the third party application and Metry.

The approval process is quite simple

  1. User clicks a "Connect with Metry" button in your application
  2. User is redirected to Metry and a consent screen
  3. User approves the third party application to access its data
  4. User is redirected back to the third party application
  5. Third party application now has access to the users energy data

Alternatives for users to approve your application

If you would prefer to not implement this flow which could be because of technical difficulties, you want to get access to a users data quickly or any other reason, there are other alternatives.

  • The user can contact support@metry.io so that we manually can approve the app on behalf of the customer. The refresh token will then be available in Metry when you are signed in to your developer account for you to manually add in your system. This works well when your application does not have many potential users with Metry. 
  • Add your application on the integrations page that all Metrys users can see and click a button to approve your application. 

1. Connect with Metry-button

The Connect with Metry button is simply a link to https://app.metry.io/id/oauth/authorize with the following query params

  • client_id: Available in the Developer portal
  • client_secret: Available in the Developer portal
  • redirect_uri: This is your web app's URL or your applications URI. But if your are testing it probably looks somthing like http://localhost.
  • grant_type: authorization_code
  • response_type: code
  • state: Optional string. It is used to pass custom variables back to your application after the user has approved access. For instance, if you have 2 buttons and want to track how many connected to your app via Button 1 vs. Button 2.
  • scope: basic
    Currently is basic the only supported official scope. Scope is used to limit the level, e.g. if your app only needs read-access, it should not request write access.

Your final URL should looks something like this:

https://app.metry.io/id/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&grant_type=authorization_code&response_type=code&state={state}&scope={scope}

2. Receive authorization code

If the user approves access for your application, Metry redirects the user back to to the redirect_uri that you provided in step 1, along with a code param that contains an authorization code. If you used the state param, it will also be included.

Example of redirect URL from Metry

http://localhost?code={authorization_code}&state={state}

Now your app need to fetch the code-param in the URL. Here is an example of how a web app can fetch the code param.

The authorization code is only valid for 10 seconds. Within this time, you need to request a long-lived refresh token.

3. Request a refresh token and access token

With the authorization code, you now make POST-request to https://app.metry.io/oauth/token with the following JSON body. The "Content-Type" header in the request must be set to "application/json".

{
  "grant_type" : "authorization_code",
  "code": {authorization_code},
  "client_id": {client_id},
  "client_secret": {client_secret},
  "redirect_uri": {redirect_uri}
}

The response includes an access_token and a refresh_token:

{
  "access_token": {access_token},
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "basic",
  "refresh_token": {refresh_token}
}

The "expires_in" means that the access_token will expire after 1 hour (3600 seconds). This is a security feature. The refresh_token will not expire automatically and that one is used to request new access_tokens when they expire. This means you should store the refresh_token in a secure and safe place.

4. Request a new access_token

When the access_token expires you make another POST-request to https://app.metry.io/oauth/token but with slightly different JSON-body:

{
  "grant_type":"refresh_token",
  "refresh_token": {refresh_token},
  "client_id": {client_id},
  "client_secret": {client_secret}
}

5. Use the API

Now you can access the user's data by passing the access_token in an "Authorization" header:

Authorization: Bearer {access_token} 

Below are some API examples, but check out https://metry.docs.apiary.io/# for more information about getting data. If you plan to export export data from Metry you should check this tutorial for some Best practice tips.

Fetch basic account information

GET https://app.metry.io/api/v2/accounts/me 

{
  "code": 200,
  "message": "OK",
  "profiling": null,
  "data": {
    "_id": "521e0be2dedcde8459000000",
    "name": "Magnus Hornef",
    "username": "example@email.com",
    "language": "sv",
  }
}

Fetch available meters

GET https://app.metry.io/api/2.0/meters?box=active&revoked=false  
{
  "code": 200,
  "message": "OK",
  "profiling": null,
  "count": 10,
  "limited_count": false,
  "skip": 0,
  "limit": 50,
  "next_page": null,
  "previous_page": null,
  "data": [
    {
      "_id": "58370da89c5111006137fe91",
      "ean": "234567",
      "name": "Flera counters",
      "address": "R\u00e4knev\u00e4gen 8",
      "timezone": "Etc\/GMT-1",
      "control_level": "manual",
      "billing_category": "manual_meter",
      "generation": 0,
      "box": "active",
      "revoked": false,
      "type": null,
    },
    {
      "_id": "5836df966c1bcd00620b28e7",
      "ean": "885599",
      "name": "Hemma",
      "address": "Johannebergsgatan 18",
      "timezone": "Etc\/GMT-1",
      "control_level": "manual",
      "billing_category": "manual_meter",
      "generation": 0,
      "box": "active",
      "revoked": false,
    }
  ]
}

Fetch consumption data

GET https://app.metry.io/api/2.0/consumptions/526f7711a158318a068b475f/month/2018 
{
  "code": 200,
  "message": "OK",
  "profiling": null,
  "data": [
    {
      "meter_id": "526f7711a158318a068b475f",
      "periods": [
        {
          "energy": [
            1915.708,
            1746.205,
            2717.46,
            1269.093,
            544.138,
            152.663,
            null,
            452.811,
            null,
            null,
            null,
            null
          ],
          "start_date": "2017-12-31T23:00:00+0000",
          "end_date": "2018-12-31T22:59:59+0000"
        }
      ]
    }
  ]
}

Related articles