Measurements

Overview

The measurements interface consists of three parts:

• The measurement API resource returns URIs and URI templates to collections of measurements, so that measurements can be queried according to various filter criteria.
• The measurement collection resource retrieves measurements and enables creating new measurements.
• The measurement resource represents individual measurements that can be queried and deleted.

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

System of units

Note that all GET requests support “X-Cumulocity-System-Of-Units” header which allows to set system of units used in response. Possible values are “imperial” or “metric”. Every measurement fragment which contains “unit” property will be transformed to use required system of units.

Most common conversions:

Examples

Example measurement:

...
{
    ....
     "c8y_Temperature": {
         "T": {
             "unit": "ºC",
             "value": 2.0791169082
         }
     }
}
...

Example request:

GET /measurement/measurements?valueFragmentType=c8y_Temperature&valueFragmentSeries=T&source=663951
Host: ...
Authorization: Basic ...
X-Cumulocity-System-Of-Units: imperial

Example response:

...
{
    ....
     "c8y_Temperature": {
        "T": {
            "unit": "°F",
            "value": 35.742410434759904
        }
    }
}
...

Measurement API

MeasurementAPI [application/vnd.com.nsn.cumulocity.measurementApi+json

The query parameter “fragmentType” is deprecated. It is still available in the API, but clients are recommended to replace the parameter with “valueFragmentType” and “valueFragmentSeries”. This leads to much better query performance. Note that you can only query fragments holding standard measurements with these parameters. Other formats cannot not be queried.

For large measurement collections querying late pages without filter can be slow as it requires the server to scan from the beginning of the input results set before beginning to return results. For cases when latest measurements should be retrieved Cumulocity recommends to narrow the scope by using time range query and base query on time stamp reported by device. Scope of query can be also significantly reduced by doing query by source.

GET the Measurement API resource

Response body: application/vnd.com.nsn.cumulocity.measurementApi+json Require role: ROLE_MEASUREMENT_READ

Example request:

GET /measurement
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.measurementApi+json;ver=...
Content-Length: ...
{
  "self" : "<<Measurement API URL>>",
  "measurements" : { "self" : "<<MeasurementCollection URL>>" },
  "measurementsForDate" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
  "measurementsForDateAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
  "measurementsForDateAndValueFragmentType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}",
  "measurementsForDateAndValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForDateAndValueFragmentTypeAndValueFragmentSeries" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForDateAndValueFragmentTypeAndValueFragmentSeriesAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}",
  "measurementsForSource" : "<<MeasurementCollection URL>>?source={source}",
  "measurementsForSourceAndDate" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
  "measurementsForSourceAndDateAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
  "measurementsForSourceAndDateAndValueFragmentType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}",
  "measurementsForSourceAndDateAndValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForSourceAndDateAndValueFragmentTypeAndValueFragmentSeries" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForSourceAndDateAndValueFragmentTypeAndValueFragmentSeriesAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}",
  "measurementsForSourceAndType" : "<<MeasurementCollection URL>>?source={source}&type={type}",
  "measurementsForSourceAndValueFragmentType" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}",
  "measurementsForSourceAndValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForSourceAndValueFragmentTypeAndValueFragmentSeries" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForSourceAndValueFragmentTypeAndValueFragmentSeriesAndType" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}",
  "measurementsForType" : "<<MeasurementCollection URL>>?type={type}",
  "measurementsForValueFragmentType" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}",
  "measurementsForValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForValueFragmentTypeAndValueFragmentSeries" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForValueFragmentTypeAndValueFragmentSeriesAndType" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}"
}

Measurement collection

MeasurementCollection [application/vnd.com.nsn.cumulocity.measurementCollection+json]

GET a collection of measurements

Response body: MeasurementCollection

Required role: ROLE_MEASUREMENT_READ

Example request: Retrieve energy readings.

 GET /measurement/measurements
 Host: ...
 Authorization: Basic ...
 Accept: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
Content-Length: ...
{
  "self":"...",
  "measurements":[
    {
      "id" : "42",
      "self" : "...",
      "time" : "2011-09-06T12:03:27.845Z",
      "type" : "KamstrupA220Reading",
      "source" : { "id": "12345", "self": "..." },
      "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
        "A+:1": { "value": 123, "unit": "kWh" },
        "A-:1": { "value": 2, "unit": "kWh" }
      },
      "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
        "A+:1": { "value": 123, "unit": "kWh" },
        "A+:2": { "value": 123, "unit": "kWh" },
        "A+:3": { "value": 123, "unit": "kWh" }
      }
    },
    {
      "id" : "43",
      "self" : "...",
      "time" : "2011-09-19T12:03:27.845Z",
      "type" : "KamstrupA220Reading",
      "source" : { "id": "12345", "self": "..." },
      "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
        "A+:1": { "value": 1234, "unit": "kWh" },
        "A-:1": { "value": 2, "unit": "kWh" }
      },
      "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
        "A+:1": { "value": 1234, "unit": "kWh" },
        "A+:2": { "value": 1234, "unit": "kWh" },
        "A+:3": { "value": 1234, "unit": "kWh" }
      }
    }
  ],
  "statistics" : {
    "totalPages" : 2,
    "pageSize" : 5,
    "currentPage : 1
  }
}

In case of executing range queries on measurements API, like query by dateFrom and dateTo, the oldest measurements are returned first. It is possible to change the order by adding query parameter “revert=true” to the request URL. In many use cases it is needed to get the latest measurement sent from the device. This can be accomplished by passing “revert” param together with “dateFrom” and “dateTo” params to sort the outcome by date, e.g. pass dateFrom from a year ago, and dateTo from the feature.

GET - retrieve all or some series of measurements

This endpoint returns a list of series (all or only those matching specified names; a series is any fragment in measurement that contains “value” property) and their values within given period. Mandatory params are: dateFrom, dateTo and source. No paging is used here. It is possible to fetch aggregated results by passing additional param: aggregationType (DAILY, HOURLY, MINUTELY). If no aggregation param is specified, the result contains no more than 5000 values. Important: for the aggregation to be done correctly the mechanism expects a device to always use the same time zone when it sends dates.

Required role: ROLE_MEASUREMENT_READ

Example request: retrieve all series.

 GET /measurement/measurements/series...
 Authorization: Basic ...
 Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...

Series can be filtered by providing additional “series” param with full name of a series (measurement type and series name). You can specify more series to filter by adding more “series” param occurrences, e.g.: …series=c8y_AccelerationMeasurement.acceleration&series=c8y_SpeedMeasurement.velocity… Because of this use case, dots must not be used in neither measurement fragment nor series.

Example request: retrieve only specific series.

 GET /measurement/measurements/series?series=c8y_AccelerationMeasurement.acceleration&dateFrom=...
 Authorization: Basic ...
 Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
{
 "values": {
     "2014-12-04T17:33:01.538+01:00": [
         {
          "min": 13.37,
          "max": 13.37
         }],
     "2014-12-04T17:34:01.774+01:00": [
         {
          "min": 10.2,
          "max": 10.2
         }]
 },
 "series": [
         {
          "unit": "m/s2",
          "name": "acceleration",
          "type": "c8y_AccelerationMeasurement"
         }],
 "truncated": false
}

Each key in “values” object is a date taken from measurement and it contains a list of min and max pairs. Each pair corresponds to single series definition in “series” object. If there is no aggregation used, min = max in every pair.

Flag “truncated” indicates whether there were more than 5000 values and if the final result was truncated.

POST - create a new measurement

Request body: Measurement

Response body: Measurement

Required role: ROLE_MEASUREMENT_ADMIN or owner of source object

Example Request:

POST /measurement/measurements
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
{
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345" },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A-:1": { "value": 2, "unit": "kWh" }
  },
  "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A+:2": { "value": 1234, "unit": "kWh" },
    "A+:3": { "value": 1234, "unit": "kWh" }
  }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
Content-Length: ...
{
  "id" : "43",
  "self" : "<<URL of new measurement>>",
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345", "self": "..." },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A-:1": { "value": 2, "unit": "kWh" }
  },
  "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A+:2": { "value": 1234, "unit": "kWh" },
    "A+:3": { "value": 1234, "unit": "kWh" }
  }
}

For POST requests, the source parameter is required to have only an id.

The “id” of the new measurement is generated by the server and returned in the response to the POST operation.

Please note that for correct visualization of measurement series on UI graphs, property names used for fragment and serie name should not contain whitespaces and special characters like [],*..

POST - create multiple measurements

POST /measurement/measurements
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
{
"measurements": [
    {
     "c8y_SpeedMeasurement": {
     	"speed": { 
     		"value": 25,
     		"unit": "km/h" }
            },
     "time":"2013-06-22T17:03:14.000+02:00", 
     "source": {
     	"id":"10200" }, 
     "type": "c8y_SpeedMeasurement"
    },
    {
     "c8y_SpeedMeasurement": {
   	 	"speed": { 
        	"value": 22,
            "unit": "km/h" }
            },
     "time":"2013-06-22T17:05:14.000+02:00", 
     "source": {
     	"id":"10200" }, 
     "type": "c8y_SpeedMeasurement"
    }
]
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
Content-Length: ...
{
 "measurements": [
    {
     "time": "2013-06-22T17:03:14.000+02:00",
     "id": "832254760",
     "self": "<<URL of new measurement>>",
     "source": {"id": "10200","self": "..."},
     "type": "c8y_SpeedMeasurement",
     "c8y_SpeedMeasurement": {
     	"speed": {
        	"unit": "km/h",
            "value": 25
            }
        }
    },
    {
     "time": "2013-06-22T17:05:14.000+02:00",
     "id": "832254761",
     "self": "<<URL of new measurement>>",
     "source": {"id": "10200","self": "..."},
     "type": "c8y_SpeedMeasurement",
     "c8y_SpeedMeasurement": {
     	"speed": {
        	"unit": "km/h",
            "value": 22
            }
        }
    }
]
}

DELETE - delete a measurement collection

The DELETE method allows for deletion of measurement collections. Applicable query parameters are equivalent to GET method.

Request body: N/A

Response body: N/A

Required role: ROLE_MEASUREMENT_ADMIN

Example request:

 DELETE: /measurement/measurements....
 Host: ...
 Authorization: Basic ...

Example response:

HTTP/1.1  204 NO CONTENT

Measurement

Measurement [application/vnd.com.nsn.cumulocity.measurement+json]

Each measurement fragment is an object containing the actual measurements as properties. The property name represents the name of the measurement, the property value is structured as follows:

GET a representation of a Measurement

Response body: Measurement

Required role: ROLE_MEASUREMENT_READ

Example request:

GET /measurement/measurements/<<measurementId>>
Host: ...
Authorization: Basic ...

Example response:

Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
Content-Length: ...
{
  "id" : "43",
  "self" : "<<URL of the measurement>>",
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345", "self": "..." },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A-:1": { "value": 2, "unit": "kWh" }
  },
  "com_cumulocity_msrmts_ThreePhaseReading": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A+:2": { "value": 1234, "unit": "kWh" },
    "A+:3": { "value": 1234, "unit": "kWh" }
  }
}

DELETE a Measurement

Request Body: N/A.

Response Message Body: N/A.

Required role: ROLE_MEASUREMENT_ADMIN or owner of source object

Example Request: Delete a measurement

DELETE /measurement/measurements/<<measurementID>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example Response:

HTTP/1.1  204 NO CONTENT

Data streaming

Measurement collection API allows to fetch the data in form of data stream. The response format stays same but data is transmitted by server directly from database element by element so it can be received in same way. Using stream json parses like java json or javascript json parsers we are able to transmit high data volumes in single request. To activate streaming you need to send as Accept header application/json-stream

Example :

 GET /measurement/measurements
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept application/json-stream

Other response formats

In order to get measurements in other formats than JSON you can use one of the following supported Accept headers:

• text/csv,
• application/vnd.ms-excel.

Notifications

The measurement notification API permits to receive updates for all measurements for a specific device. The basic protocol for receiving notifications is described in the Section “Real-time notifications”. The URL is

/cep/realtime

The subscription channel needs to contain the managed object ID of the device or a “*” as placeholder to receive notifications for the measurements of all devices

/measurements/<<deviceId>>

The response will additionally to the measurement object contain a “realtimeAction” to identify which action resulted in the given object (CREATE, UPDATE or DELETE). In case of a deletion the data will only contain the id of the deleted measurement.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/measurement/12345",
    "successful": true,
    "error": "",
    "data": [{
      "realtimeAction": "CREATE",
      "data": {
        "id": "1",
        "self": "...",
        "source": {
          "12345"
        },
        "creationTime": "2011-09-06T12:03:27.927+02:00",
        "c8y_TemperatureMeasurement": {
          "T": {
            "value": 25,
            "unit": "C"
          }
        },
        "time":"2011-09-06T12:03:17.927+02:00",
        "type": "TemperatureMeasurement"
      }
    }],
    "clientId": "Un1q31d3nt1f13r"
  }
]

Required role: ROLE_MEASUREMENT_READ