Measurement Data

Measurements are commonly conducted on a weekly basis. Congrid exposes an API to fetch the measurement data in the system. The measurements are created with the Congrid mobile application.

For the sake of this tutorial we have created a few measurements for our tutorial project. The creation of the measurements is out of scope for this tutorial and is not described here in detail.

The API exposes two different ways for retrieving the measurements:

  • Retrieve measurements of a single project
  • Retrieve measurements of all projects

Both of these are described below in more detail.

The measurement entity contains information that is related to the whole measurement. This information is for example the creation date, the result of the measurement etc. Commonly the measurement has a various number of topics that describe in more detail what is measured. The API also exposes end-points to retrieve those topics related to a measurement. This is described the end of this chapter.


NOTE: By default the end-points only return data about completed measurements, i.e. measurements that have one of the following statusId: COMPLETED, ACCEPTED, REJECTED, VERIFIED.

Use the optional statusId query parameter to fetch data of measurements with a different statusId value.


Fetching measurements of a single project

To fetch all the measurements for a single project perform a GET to the following end-point and change the {projectId} with the actual id of the project.

/projects/{projectId}/measurements

Example requests:

curl
JavaScript
curl -X GET -H "Content-Type: application/json" -H "Congrid-API-Token: YOUR-API-TOKEN" \
  "https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/measurements"
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/measurements',
  headers: 
   { 'congrid-api-token': 'YOUR-API-TOKEN',
     'content-type': 'application/json' } };
     
request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response:

{
  "count": 2,
  "pageSize": 100,
  "results": [
    {
      "createdAt": "2017-01-25T05:35:55.588Z",
      "measurementCategoryId": "EXTERNAL",
      "measurementId": "23386",
      "measurementTypeId": "TR",
      "modifiedAt": "2017-01-25T05:36:49.354Z",
      "name": "TR vko. 3, Measurement 2",
      "projectCode": "A-123456",
      "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ",
      "projectName": "Tutorial project",
      "result": 78.6,
      "statusId": "COMPLETED",
      "weekNumber": 3,
      "year": 2017
    },
    {
      "createdAt": "2017-01-25T05:32:52.223Z",
      "measurementCategoryId": "EXTERNAL",
      "measurementId": "23384",
      "measurementTypeId": "TR",
      "modifiedAt": "2017-01-25T05:34:07.488Z",
      "name": "TR vko. 4, Measurement 1",
      "projectCode": "A-123456",
      "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ",
      "projectName": "Tutorial project",
      "result": 78.8,
      "statusId": "COMPLETED",
      "weekNumber": 4,
      "year": 2017
    }
  ]
}

Fetching measurements from a time period

To fetch measurements from a certain time range use the modifiedAtGt, modifiedAtGte, modifiedAtLt, modifiedAtLte query parameters.

A common approach is to automate the fetching of measurements for example on a daily basis. One could use the following queries to fetch the measurements from two subsequent days:

For the first day:

/projects/{{projectId}}/measurements?modifiedAtGte=2017-01-01T00:00:00&?modifiedAtLt=2017-01-02T00:00:00

For the second day:

/projects/{{projectId}}/measurements?modifiedAtGte=2017-01-02T00:00:00&?modifiedAtLt=2017-01-03T00:00:00

Fetching measurements from all projects

The API exposes a convenience end-point to fetch all the measurements of all the projects in the system:

/measurements

This end-point accepts the same list of modifiedAt query parameters as the end-point to fetch per project measurements.

Example requests:

curl
JavaScript
curl -X GET -H "Content-Type: application/json" -H "Congrid-API-Token: YOUR-API-TOKEN" \
  "https://api.congrid.com/v1/measurements"
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.congrid.com/v1/measurements',
  headers: 
   { 'congrid-api-token': 'YOUR-API-TOKEN',
     'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response:

    {
      "count": 2,
      "pageSize": 100,
      "results": [
        {
          "createdAt": "2017-01-25T05:35:55.588Z",
          "measurementCategoryId": "EXTERNAL",
          "measurementId": "23386",
          "measurementTypeId": "TR",
          "modifiedAt": "2017-01-25T05:36:49.354Z",
          "name": "TR vko. 3, Measurement 2",
          "projectCode": "A-123456",
          "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ",
          "projectName": "Tutorial project",
          "result": 78.6,
          "statusId": "COMPLETED",
          "weekNumber": 3,
          "year": 2017
        },
        {
          "createdAt": "2017-01-25T05:32:52.223Z",
          "measurementCategoryId": "EXTERNAL",
          "measurementId": "23384",
          "measurementTypeId": "TR",
          "modifiedAt": "2017-01-25T05:34:07.488Z",
          "name": "TR vko. 4, Measurement 1",
          "projectCode": "A-123456",
          "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ",
          "projectName": "Tutorial project",
          "result": 78.8,
          "statusId": "COMPLETED",
          "weekNumber": 4,
          "year": 2017
        }
      ]
    }

Note that the response is exactly the same as in the previous example where we fetched all the measurements of one project. This is because there is only one project in the system for the company. With real life data the response would contain all the measurements from all projects.

Measurement topics

To fetch the measurement topics of a particular measurement one can use the root level end-point for fetching the topics and limit the response through the measurementId query parameter.

/measurementTopics?measurementId={measurementId}

Below is an example to fetch the measurement topics of one of the measurements with measurement id 223386 above:

Request:

curl
JavaScript
curl -X GET -H "Content-Type: application/json" -H "Congrid-API-Token: YOUR-API-TOKEN" \
  "https://api.congrid.com/v1/measurementTopics?measurementId=23386"
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.congrid.com/v1/measurementTopics',
  qs: { measurementId: '23386' },
  headers: 
   { 'congrid-api-token': 'YOUR-API-TOKEN',
     'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response:

{
  "count": 7,
  "pageSize": 100,
  "results": [
    {
      "id": "125467",
      "measurementId": "23386",
      "name": "Sähkö ja valaistus",
      "negativeMultiplier": 1,
      "orderNumber": "5",
      "plusCount": 8,
      "positiveMultiplier": 1,
      "templateId": "5"
    },
    {
      "id": "125464",
      "measurementId": "23386",
      "name": "Telineet, kulkusillat ja tikkaat",
      "negativeMultiplier": 1,
      "orderNumber": "2",
      "plusCount": 0,
      "positiveMultiplier": 1,
      "templateId": "2"
    },
    {
      "id": "125469",
      "measurementId": "23386",
      "name": "Pölyisyys",
      "negativeMultiplier": 1,
      "orderNumber": "6b",
      "plusCount": 3,
      "positiveMultiplier": 1,
      "templateId": "7"
    },
    {
      "id": "125466",
      "measurementId": "23386",
      "name": "Putoamissuojat",
      "negativeMultiplier": 1,
      "orderNumber": "4",
      "plusCount": 0,
      "positiveMultiplier": 1,
      "templateId": "4"
    },
    {
      "id": "125468",
      "measurementId": "23386",
      "name": "Järjestys ja jätehuolto",
      "negativeMultiplier": 1,
      "orderNumber": "6a",
      "plusCount": 0,
      "positiveMultiplier": 1,
      "templateId": "6"
    },
    {
      "id": "125463",
      "measurementId": "23386",
      "name": "Työskentely",
      "negativeMultiplier": 1,
      "orderNumber": "1",
      "plusCount": 6,
      "positiveMultiplier": 1,
      "templateId": "1"
    },
    {
      "id": "125465",
      "measurementId": "23386",
      "name": "Koneet ja välineet",
      "negativeMultiplier": 1,
      "orderNumber": "3",
      "plusCount": 5,
      "positiveMultiplier": 1,
      "templateId": "3"
    }
  ]
}

results matching ""

    No results matching ""