Table of contents


Retrieve energy readings


Introduction

This call allows you to request the so-called energy readings for a given installation/site for a given period and interval. To be able to access the data, you are required to have a valid and active token (see Authentication for more details).


Get the energy readings for a given site/installation

The energy readings consist of various data attributes, which can be combined to give a total amount. The values of the different data attributes for the given period and interval are returned, and the sum of the attributes is also included in the response of the endpoint.

Endpoint:

/v2/installations/{installation ID}/stats?type=kwh

Required parameters (GET):

start: Unix timestamp of the starting timestamp for which the stats should be retrieved

end: Unix timestamp of the ending timestamp for which the stats should be retrieved.

Please note: the granularity of our data is one hour, so if you want to make sure you retrieve accurate statistics, please round your start and end timestamps to closest whole hour, e.g.:

1486022639
should become:
1486022400
or
1486026000

interval: Interval for which the stats should be grouped in. Possible values: 15mins, hours, days, weeks, months and years

NOTE: At the moment of documenting the 15mins interval feature, the data is not yet stored in the database. Right now, the CCGX is sending the data on an hourly interval. One of the next firmware updates will contain the change to send, and therefore store, the data with an increased resolution, the 15 minute interval. Using the 15 minute interval on data stored per hour will result in an hourly interval until the firmware upgrade: the returned recordset will only contain records for the whole hour. And no records for the other three 15 minute intervals.

There is a maximum allowed time period for each interval, which is:

Requesting a larger time period will result in an error:

{"success":false,"error_code":"no_data","errors":["Site has no stats for this period."]}

type: You can choose between two types of data to be obtained: kwh and custom. kwh has a predefined set of attributes that reflect the most common kWh data of the installation. If other attributes should be obtained, for the installation use the type custom.

attributeCodes[]: Specify which attributeCodes to retrieve. Works only with type=custom. Multiple codes can be sent using the format:

attributeCodes[]=Gb&attributeCodes[]=Gc
For a full list of attributes see: Available energy reading attributes

show_instance (default = 0): When show_instance=1, all the values per attribute are grouped per instance. Otherwise the values of all instances are assigned to the given installation. Note that when using show_instance=1 the format of the response changes to support the results per instance.

Method:

GET

The response will be something like this for for example:

/v2/installations/975/stats?type=kwh&start=1441066216&end=1442067216&interval=days

{
  "success": true,
  "records": {
    "Pc": [
      [
        1441066216000,
        12.927161
      ],
      [
        1441152616000,
        28.52883
      ],
      [
        1441239016000,
        17.722068
      ],
      [
        1441325416000,
        9.1537885
      ],
      [
        1441411816000,
        4.453626
      ],
      [
        1441498216000,
        4.5079915
      ],
      [
        1441584616000,
        16.8285763
      ],
      [
        1441671016000,
        12.1123506
      ],
      [
        1441757416000,
        29.2207336
      ],
      [
        1441843816000,
        29.7107766
      ],
      [
        1441930216000,
        13.5401983
      ],
      [
        1442016616000,
        5.872294
      ]
    ]
  },
  "totals": {
    "Pb": 2.5122129,
    "Pc": 184.5783944,
    "Gb": 9.3752899,
    "Gc": 252.0008088,
    "Pg": 64.7871119,
    "Bc": 0.0182044,
    "kwh": 513.2720223
  }
}


Retrieving aggregated statistics

This endpoint returns the total consumption / solar stats for a given installation for four time periods, year, month week and today. You cannot specify an interval or start and end.

GET /v2/installations/1039/overallstats
Returns aggregated statistics used in the live feed interface for the installation.

GET /v2/installations/1039/overallstats?type=<type>
Returns aggregated statistics of the specified type.

Optional parameters:

type: You can choose between two types of data to be obtained: kwh and custom. kwh has a predefined set of attributes that reflect energy readings. If other attributes should be obtained, use the type custom. See next field to specify which attributes to obtain.

attributeCodes[]: Specify which attributeCodes to retrieve. Works only with type=custom. Multiple codes can be sent using the format:

attributeCodes[]=Gb&attributeCodes[]=Gc

All available energy reading attributes can be found here:

List of available attributes

Sample response:

{
  "success": true,
  "records": {
    "year": {
      "totals": {
        "Gc": 2890.3096331091,
        "Pc": 444.43205584318,
        "Bc": 285.16498499073,
        "gc": false
      },
      "percentages": {
        "Gc": 80,
        "Pc": 12,
        "Bc": 8,
        "gc": 0
      }
    },
    "month": {
      "totals": {
        "Gc": 181.18626743555,
        "Pc": 109.40366000833,
        "Bc": 46.909044223721,
        "gc": false
      },
      "percentages": {
        "Gc": 54,
        "Pc": 32,
        "Bc": 14,
        "gc": 0
      }
    },
    "week": {
      "totals": {
        "Gc": 52.626889668405,
        "Pc": 20.215319919633,
        "Bc": 7.2363689020276,
        "gc": false
      },
      "percentages": {
        "Gc": 66,
        "Pc": 25,
        "Bc": 9,
        "gc": 0
      }
    },
    "today": {
      "totals": {
        "Gc": 5.9271823316813,
        "Pc": 2.7864799629897,
        "Bc": 2.0481022689492,
        "gc": false
      },
      "percentages": {
        "Gc": 55,
        "Pc": 26,
        "Bc": 19,
        "gc": 0
      }
    }
  }
}