WEB API

The Triangulum data can be accessed through a Web API. The response to a Web API request is returned in a json format. A request can be made manually, for an easy exploration of the dataset, of programmatically. Either way, the key aspect of using the Web API is that the elements in the dataset and their corresponding data can be accessed via specific URLs.

 
Manual Web API requests

 

Manual Web API requests are made by simply entering specific URLs in the address bar of the web browser. The following URL, for example, provides access to the Triangulum dataset:

 

https://vm-pi-p02.ds.man.ac.uk/piwebapi/assetdatabases/D0XpbRmwnc7kq0OSy1LydJJQ101eEFwILkS6xbc3_4ofWgVk0tUEktUDAxLkRTLk1BTi5BQy5VS1xUUklBTkdVTFVN/elements

 

The json-formatted response of this request is shown in the screenshot below.

Looking at the json response to the above request, we can see that the elements of the dataset are listed in a dictionary called Items. All the elements in Items have  the same structure. In particular every element is characterised by a Name, a WebId and a set of Links.

 

The WebId uniquely identifies the element in the dataset and can be used to construct URL requests that pertain to that specific element.

 

In Links you can access the element's attributes and its sub-elements (among other things). For example, by clicking on the Elements link of the "Air Quality" element you will retrieve a list of items corresponding to the "Air Quality" sub-elements, as shown in the screenshot below.

The first element in this new Items list is "Oxford Road", the second "Piccadilly", and so on. Every element in this new list is a sub-element (or child-element) of "Air Quality". In this way you can drill down the Triangulum dataset until you reach the leaves of its hierarchical structure.

 

The data pertaining to the different elements of the dataset is referred to by the elements' attributes. The elements' attributes can be thought of as tags pointing to a specific stream of data. For example, the "Oxford Road" element (which is a sub-element of "Air Quality") has attributes such as "NO level", "SO2 level", "PM10 level" etc, each referring to a consistent stream of time-stamped values. To retrieve the list of attributes of a given element, you just have to click on the Attributes link of the element.

Notable URL structures for Web API requests

 

In this section we provide you with a list of URL structures that you can use to retrieve data or elements from the Triangulum dataset. In what follows replace:

  • <servername> with 'vm-pi-p02.ds.man.ac.uk' (without quotes)

  • <WebId> with the WebID of the element or attribute in question

  • <startTime> with a datetime string formatted as 'yyyy/MM/ddTHH:mm:ssZ' (without quotes)

  • <endTime> with a datetime string formatted as 'yyyy/MM/ddTHH:mm:ssZ' (without quotes)

  • <interval> with a time interval string formatted as 'HH:mm:ss' (without quotes)

 

Retrieve a specific element from the dataset

URL = https://<servername>/piwebapi/elements/<WebId>

 

Retrieve list of child elements for a given element E

URL = https://<servername>/piwebapi/elements/<WebId>/elements

Retrieve list of attributes of a specific element E

URL = https://<servername>/piwebapi/elements/<WebId>/attributes

Retrieve the last value (chronologically) or an attribute A

URL = https://<servername>/piwebapi/attributes/<WebId>/value

Retrieve the recorded values of an attribute in a given time span

URL = https://<servername>/piwebapi/streamsets/<WebId>/recorded?startTime=<startTime>&endTime<endTime>

Retrieve the interpolated values of an attribute in a given time span

URL = https://<servername>/piwebapi/streamsets/<WebId>/interpolated?interval=<interval>&startTime<startTime>&endTime=<endTime>

 
Programmatic Web API requests

 

Once the dataset's nested structure and its manual navigation is clear, the programmatic access to the data is straightforward.

 

The following python snippet, for example, retrieves the root of the Triangulum dataset and transforms it in a python dictionary:

 

import requests, json

url = 'https://vm-pi-p02.ds.man.ac.uk/piwebapi/assetdatabases/D0XpbRmwnc7kq0OSy1LydJJQ101eEFwILkS6xbc3_4ofWgVk0tUEktUDAxLkRTLk1BTi5BQy5VS1xUUklBTkdVTFVN/elements'
resp = requests.request("GET", url, headers={})
data = json.loads(resp.text)

 

The python dictionary data contain the response of our Web API request and it's structure mirrors exactly the json structure shown in the first snapshot.

Project funded by

EU's Horizon 2020,

grant No. 646578

Manchester-I