Retrieving Time Series Data from Onboarded Users

This document explains how the Glow APIs are used to access smart meter data from the properties of energy consumers who have provided consent for their smart meter data to be retrieved by Hildebrand and made available to your organisation.

By the end of this document, organisation users should have an understanding of how to retrieve time series data for their organisation’s energy consumers, and the base knowledge required to use the remainder of our APIs.

If you have further questions, please check the FAQ in the Developer's Portal or email support@glownetzero.com

Prerequisites to Data Access

In order to access data via the Glow APIs on behalf of an organisation, an active account for the Glow Development Portal is required.

To set up a new Development portal user, please navigate to our previous page here.

Data Retrieval for Time Series Data

Energy and sensor data is stored in a time series that can be retrieved as follows (each step is described in more detail below).

For a full list of the available Resource APIs, please visit this folder.

Retrieve all users from the Glow Platform

This is an optional step.

Get the virtual entities of each user

By skipping Step 1, you can instead retrieve all the virtual entities you have access to.

Get the full definition of resources that belong to a particular virtual entity

Get the time series data of a particular resource

Step 1: Retrieve all Users

In the Glow Platform, each energy consumer is a user and is mapped to a unique identifier known as their userId. A userId has access to one or more applications. Their data is held in resources (described in more detail in Step 3), which are grouped in virtual entities.

To retrieve the complete user base of your application, use the following query:

API req	https://api.glowmarkt.com/api/v0-1/account
Authentication required	Basic Auth
Headers	Content-Type: application/json Authorization Header(Basic Auth)
Example cURL	curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic BASIC_AUTH_KEY” "https://api.glowmarkt.com/api/v0-1/account"
Swagger reference	https://api.glowmarkt.com/api-docs/v0-1/usersys/usertypes/#/account/getAccounts

The response will be in JSON and will be an array of user documents.

A user document looks like this (the userID listed below will deliver sample data as described below):

{
    "createdAt": "2018-03-23T10:12:18.454Z",
    "updatedAt": "2018-03-23T10:12:18.454Z",
    "directoryId": "ac164539-5d7a-4cf9-8478-ca25b6d81ef0",
    "applicationId": "c72ef3b8-eeb1-4f64-9abd-96eda813c068",
    "userId": "41ad1a43-cdaf-4f48-b48c-1577d2edd65b",
    "accountId": "4df0241d-d074-4b30-b0df-bd1dbb94bd28",
    "status": "active",
    "active": true,
    "name": "Tester",
    "username": "tester@glowtest.com"
  }

Step 2: Get all Virtual Entities

To retrieve a specific user’s virtual entities, use the following query:

API req	GET https://api.glowmarkt.com/api/v0-1/virtualentity
Authentication required	Basic Auth
Headers	Content-Type: application/json Authorization Header(Basic Auth) userId (optional)
Example cURL	curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic BASIC_AUTH_KEY” -H "userId: b0f1b774-a586-4f72-9edd-27ead8aa7a8d" “https://api.glowmarkt.com/api/v0-1/virtualentity"
Swagger reference	https://api.glowmarkt.com/api-docs/v0-1/vesys/#/Virtual%20Entity/virtualentity_findAll

To retrieve all the virtual entities your application has access to, do not add the userId on the headers of the request.

The response will be in JSON, and will be an array of virtual entity documents. Each virtual entity will have a name, a unique identifier (veId), and a field named resources that will list all the resources that belong to that particular virtual entity.

[
  {
    "name": "Smart Home 1",
    "veId": "dc9069a7-7695-43fd-8f27-16b1c94213da",
    "veTypeId": "cc90b599-2705-4b13-98d4-3306f81169cf",
    "ownerId": "f78a3812-d4fc-4b00-99c5-20fd581721a6",
    "applicationId": "b0f1b774-a586-4f72-9edd-27ead8aa7a8d",
    "updatedAt": "2018-10-26T17:10:02.670Z",
    "createdAt": "2018-10-26T17:10:02.670Z",
    "resources": [
      {
 	"resourceId": "73f70bcd-3743-4009-a2c4-e98cc959c030",
        "resourceTypeId": "ea02304a-2820-4ea0-8399-f1d1b430c3a0"
      },
      {
        "resourceId": "b120977-aeb6-4b56-a0d3-d4a9b485848a",
        "resourceTypeId": "b4158501-a678-484a-837a-874194d3bd48"
      },
      {
        "resourceId": "b320977-aeb6-4b56-a0d3-d4a9b485848a",
        "resourceTypeId": "32d9821b-34fd-46d1-9ba1-56259afd4734"
      },
      {
        "resourceId": "b420977-aeb6-4b56-a0d3-d4a9b485848a",
        "resourceTypeId": "672b8071-44ff-4f23-bca2-f50c6a3ddd02"
      }
    ]
  },
  {
    "name": "Smart Business 2",
    "veId": "dc9069a7-7695-43fd-8f27-16b1c94213da",
    "veTypeId": "cc90b599-2705-4b13-98d4-3306f81169cf",
    "ownerId": "f78a3812-d4fc-4b00-99c5-20fd581721a6",
    "applicationId": "b0f1b774-a586-4f72-9edd-27ead8aa7a8d",
    "updatedAt": "2018-11-26T17:10:02.670Z",
    "createdAt": "2018-11-26T17:10:02.670Z",
    "resources": [
      {
        "resourceId": "74f70bcd-3743-4009-a2c4-e98cc959c030",
        "resourceTypeId": "ea02304a-2820-4ea0-8399-f1d1b430c3a0"
      },
      {
        "resourceId": "c120977-aeb6-4b56-a0d3-d4a9b485848a",
        "resourceTypeId": "b4158501-a678-484a-837a-874194d3bd48"
      },
      {
        "resourceId": "c320977-aeb6-4b56-a0d3-d4a9b485848a",
        "resourceTypeId": "32d9821b-34fd-46d1-9ba1-56259afd4734"
      },
      {
        "resourceId": "c420977-aeb6-4b56-a0d3-d4a9b485848a",
        "resourceTypeId": "672b8071-44ff-4f23-bca2-f50c6a3ddd02"
      }
    ]
  }
]

Get a Virtual Entity with the full definition of resources

Any incoming data from smart meters, sensors and devices etc, is stored in what we call resources. Typically, a resource represents a single data stream. Each resource has a unique identifier within the Glowmarkt platform, called a resourceId.

From Step 2, you already have the unique identifiers of each resource, so you can skip this step and move directly to Step 4.

If you wish to retrieve the full definition of all the resources that belong to a particular virtual entity, use the following query:

API req	GET https://api.glowmarkt.com/api/v0-1/virtualentity/dc9069a7-7695-43fd-8f27-16b1c94213da/resources
Authentication required	Basic Auth
Headers	Content-Type: application/json Authorization Header(Basic Auth)
Example cURL	curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic BASIC_AUTH_KEY” "https://api.glowmarkt.com/api/v0-1/virtualentity/dc9069a7-7695-43fd-8f27-16b1c94213da/resources"
Swagger reference	https://api.glowmarkt.com/api-docs/v0-1/vesys/#/Virtual%20Entity/virtualentity_findResourcesbyVeId

The response will be in JSON, and will be the virtual entity document. Under the resources array, the full definition of each resource will be provided.

{
  "name": "Smart Home 1",
  "veId": "dc9069a7-7695-43fd-8f27-16b1c94213da",
  "veTypeId": "cc90b599-2705-4b13-98d4-3306f81169cf",
  "ownerId": "51ad1a43-cdaf-4f48-b48c-1577d2edd65b",
  "applicationId": "b0f1b774-a586-4f72-9edd-27ead8aa7a8d",
  "updatedAt": "2018-10-26T17:10:02.670Z",
  "createdAt": "2018-10-26T17:10:02.670Z",
  "resources": [
    {
      "resourceId": "73f70bcd-3743-4009-a2c4-e98cc959c030",
      "resourceTypeId": "ea02304a-2820-4ea0-8399-f1d1b430c3a0",
      "name": "electricity",
      "classifier": "electricity.consumption",
      "description": "electricity consumption",
      "ownerId": "f78a3812-d4fc-4b00-99c5-20fd581721a6",
      "baseUnit": "kWh",
      "active": true
    },
    {
      "resourceId": "b120977-aeb6-4b56-a0d3-d4a9b485848a",
      "resourceTypeId": "b4158501-a678-484a-837a-874194d3bd48",
      "name": "electricity cost",
      "classifier": "electricity.consumption.cost",
      "description": "electricity cost",
      "ownerId": "f78a3812-d4fc-4b00-99c5-20fd581721a6",
      "baseUnit": "pence",
      "active": true
    },
    {
      "resourceId": "b320977-aeb6-4b56-a0d3-d4a9b485848a",
      "resourceTypeId": "32d9821b-34fd-46d1-9ba1-56259afd4734",
      "name": "gas",
      "classifier": "gas.consumption",
      "description": "gas consumption",
      "ownerId": "f78a3812-d4fc-4b00-99c5-20fd581721a6",
      "baseUnit": "kWh",
      "active": true
    },
    {
      "resourceId": "b420977-aeb6-4b56-a0d3-d4a9b485848a",
      "resourceTypeId": "672b8071-44ff-4f23-bca2-f50c6a3ddd02",
      "name": "gas cost",
      "classifier": "gas.consumption.cost",
      "description": "gas cost",
      "ownerId": "f78a3812-d4fc-4b00-99c5-20fd581721a6",
      "baseUnit": "pence",
      "active": true
    }
  ]
}

The classifier field on the resource document indicates the data type. Examples of classifiers are:

Classifier Identifier	Description
electricity.consumption	The electricity readings of a customer in energy units (kWh).
electricity.consumption.cost	The electricity readings of a customer in monetary units (pence).
electricity.export	Electricity exported from a site, measured in energy units (kWh).
electricity.import.reactive	Reactive electricity imported at a site, measured in energy units (kVARh). This represents power that is out of phase with active power due to equipment such as capacitors and inductors. This data is typically relevant for larger non-domestic sites.
electricity.export.reactive	The export reactive energy for electricity of a site in energy units (kVARh). This data is typically useful for large non-domestic sites.
gas.consumption	The gas readings of a customer in energy units (kWh).
gas.consumption.cost	The gas readings of a customer in monetary units (pence).

If a property has an electricity and a gas meter installed, there will be four resources: electricity consumption, electricity cost, gas consumption, gas cost.

Electricity only customers will have two resources: electricity consumption, electricity cost.

The type of resources that are attached to a virtual entity depend on the type of the application.

Step 4: Get the Resource readings

To retrieve the time series data of a resource, make the following query:

API req	GET https://api.glowmarkt.com/api/v0-1/resource/1ddbfcb4-2ff1-4812-a425-1952f323c763/readings?from=2018-04-10T00:00:00&to=2018-04-23T23:59:59&period=P1D&offset=-60&function=sum
API Syntax	https://api.glowmarkt.com/api/v0-1/resource/{{resourceId}}/readings?from=YYYY-MM-DDTHH:MM:SS&to=YYYY-MM-DDTHH:MM:SS&period=P1D&offset=-60&function=sum
Authentication required	Basic Auth
Headers	Content-Type: application/json Authorization Header(Basic Auth)
Example cURL	curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic BASIC_AUTH_KEY" “https://api.glowmarkt.com/api/v0-1/resource/1ddbfcb4-2ff1-4812-a425-1952f323c763/readings?from=2018-04-10T00:00:00&to=2018-04-23T23:59:59&period=P1D&offset=-60&function=sum"
Swagger reference	https://api.glowmarkt.com/api-docs/v0-1/resourcesys/#/Resource/resource_getReading

The query parameters that can be used are:

Query Parameter	Description
from	The date, data is required from. The date time syntax is yyyy-mm-ddThh:mm:ss
to	The date, data is required to. The date time syntax is yyyy-mm-ddThh:mm:ss
offset	All the data we store is saved in UTC (Coordinated Universal Time), regardless of the timezone it was collected in. Note: UK smart meters timestamp in UTC. For the API to correctly return the data for the period you request you must supply the offset in minutes between the timezone you require and UTC. As an example if you wish to request data in BST (British Summer Time, UTC+1) you should specify an offset of -60. EST (East Coast N America) would be +300.
function	The aggregating function that will be applied to the data. (Use sum to get total reading per period).
period	The aggregation level in which the data is to be returned (ISO 8601). PT1M (minute level, only elec) PT30M (30 minute level) PT1H (hour level) P1D (day level) P1W (week level, starting Monday) P1M (month level) P1Y (year level)

This is an example response:

{
  "status": "OK",
  "name": "electricity consumption",
  "resourceTypeId": "ea02304a-2820-4ea0-8399-f1d1b430c3a0",
  "resourceId": "73f70bcd-3743-4009-a2c4-e98cc959c030",
  "query": {
    "from": "2018-04-10T00:00:00",
    "to": "2018-04-11T23:59:59",
    "period": "P1D"
  },
  "data": [
    [
      1523318400,
      48.79
    ],
    [
      1523404800,
      48.826
    ]
  ]
}

All the data is under the data field. The data is an array of arrays.

[
	[UTC timestamp, reading],
	[UTC timestamp, reading],
]

Important: depending on the aggregation period, there is a limit to the volume of data that can be requested per query as follows:

Period Parameter	Description	Limit in days
PT1M	1-minute level	2 days
PT30M	30-minute level	10 days
PT1H	1-hour level	31 days
P1D	1-day level	31 days
P1W	1-week level	6 weeks
P1M	1-month level	365 days
PIY	1-year level	365 days

When the aggregation periods of P1W and P1M are used, the start date of the query (“to” date) should be set to the beginning of the week (Monday) or month respectively (1st day).

An overview on using our APIs in a video is available here .

Retrieving Time Series Data from Onboarded Users

Prerequisites to Data Access#

Data Retrieval for Time Series Data#

Step 1: Retrieve all Users#

Step 2: Get all Virtual Entities#