Measurements

Overview

The measurements interface consists of three parts:

For all POST requests an accept header should be provided, otherwise an empty response body will be returned.

System of units

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

Most common conversions:

Metric Imperial
m (meter) ft (foot)
km (kilometer) mi (mile)
cm (centimeter) in (inch)
°C (degree Celsius) °F (degree Fahrenheit)
K (Kelvin) °R (degree Rankine)
g (gram) oz (ounce)
kg (kilogram) lb (pound)

Examples

Example measurement: 

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

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}} 
GET <<url>>/measurement/measurements?valueFragmentType=c8y_Temperature&valueFragmentSeries=T&source=<<sourceID>>

Example response

HEADERS
Content-Type application/vnd.com.nsn.cumulocity.measurementcollection+json;ver=… 
HTTP/1.1
200 OK
...
{
    ....
     "c8y_Temperature": {
        "T": {
            "unit": "°F",
            "value": 35.742410434759904
        }
    }
}
...

Measurement API

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

Name Type Occurs Description
self string 1 A URL linking to this resource.
measurements Measurement Collection 1 Collection of all measurements.
measurementsForDate MeasurementCollection URI template 1 Read-only collection of all measurements from a particular period (placeholder {dateFrom} and {dateTo}).
measurementsForDateAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular type and being from a particular period (placeholder {type}, {dateFrom} and {dateTo}).
measurementsForDateAndValueFragmentType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value and being from a particular period (placeholder {valueFragmentType}, {dateFrom} and {dateTo}).
measurementsForDateAndValueFragmentType AndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value and being from a particular period and type object (placeholder {valueFragmentType}, {dateFrom}, {dateTo} and {type}).
measurementsForDateAndValueFragmentType AndValueFragmentSeries MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and fragment series with value and being from a particular period (placeholder {valueFragmentType}, {valueFragmentSeries}, {dateFrom}, {dateTo}).
measurementsForDateAndValueFragmentType AndValueFragmentSeriesAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and fragment series with value and being from a particular period and type object (placeholder {valueFragmentType}, {valueFragmentSeries}, {dateFrom}, {dateTo} and {type}).
measurementsForSource MeasurementCollection URI template 1 Read-only collection of all measurements coming from a particular source object (placeholder {source}).
measurementsForSourceAndDate MeasurementCollection URI template 1 Read-only collection of all measurements from a particular period and from a particular source object (placeholder {dateFrom}, {dateTo} and {source}).
measurementsForSourceAnd DateAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular type and being from a particular period and source object (placeholder {type}, {dateFrom}, {dateTo} and {source}).
measurementsForSourceAndDate AndValueFragmentType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value and being from a particular period and source object (placeholder {valueFragmentType}, {dateFrom}, {dateTo} and {source}).
measurementsForSourceAnd DateAndValueFragmentTypeAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value and type object and being from a particular period and source object (placeholder {valueFragmentType}, {dateFrom}, {dateTo}, {type} and {source}).
measurementsForSourceAndDateAnd ValueFragmentTypeAndValueFragmentSeries MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and series with value and being from a particular period and source object (placeholder {valueFragmentType}, {valueFragmentSeries}, {dateFrom}, {dateTo} and {source}).
measurementsForSourceAndDateAndValueFragmentType AndValueFragmentSeriesAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and series with value and type object and being from a particular period and source object (placeholder {valueFragmentType}, {valueFragmentSeries}, {dateFrom}, {dateTo}, {type} and {source}).
measurementsForSourceAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular type and coming from a particular source object (placeholder {type} and {source}).
measurementsForSourceAndValueFragmentType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value and coming from a particular source object (placeholder {valueFragmentType} and {source}).
measurementsForSourceAndValueFragmentTypeAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value and a particular type and source object (placeholder {valueFragmentType}, {type} and {source}).
measurementsForSourceAndValueFragmentType AndValueFragmentSeries MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and series with value and coming from a particular source object (placeholder {valueFragmentType}, {valueFragmentSeries} and {source}).
measurementsForSourceAndValueFragmentType AndValueFragmentSeriesAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and series with value and a particular type and source object (placeholder {valueFragmentType}, {valueFragmentSeries}, {type} and {source}).
measurementsForType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular type (placeholder {type}).
measurementsForValueFragmentType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type with value (placeholder {valueFragmentType}).
measurementsForValueFragmentTypeAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular type and a particular fragment type with value(placeholder {type} and {valueFragmentType}).
measurementsForValueFragmentType AndValueFragmentSeries MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular fragment type and series with value (placeholder {valueFragmentType} and {valueFragmentSeries}).
measurementsForValueFragmentTypeAndValueFragmentSeriesAndType MeasurementCollection URI template 1 Read-only collection of all measurements containing a particular type and a particular fragment type and series with value(placeholder {type}, {valueFragmentType} and {valueFragmentSeries}).

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 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 IoT 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 - Measurement API resource

Response body: application/vnd.com.nsn.cumulocity.measurementapi+json

Require role: ROLE_MEASUREMENT_READ

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}} 
GET <<url>>/measurement

Example response

HEADERS
Content-Type application/vnd.com.nsn.cumulocity.measurementapi+json;ver=… 
HTTP/1.1
200 OK

{
  "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]

Name Type Occurs Description
self string 1 A URL linking to this resource.
measurements Measurement 0..n List of measurements, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev string 0..1 A URI linking to a potential previous page of measurements.
next string 0..1 A URI linking to a potential next page of measurements.

GET - Collection of measurements

Response body: MeasurementCollection

Required role: ROLE_MEASUREMENT_READ

Example request - Retrieve energy readings

HEADERS
Authorization {{auth}}
Host {{hostname}} 
 GET <<url>>/measurement/measurements

Example response

HEADERS
Content-Type application/vnd.com.nsn.cumulocity.measurementcollection+json;ver=… 
HTTP/1.1
200 OK

{
  "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 the query parameter “revert=true” to the request URL. In many use cases it is required 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.

Note that the source parameter is optional in the /measurement/measurements endpoint. If a user doesn’t have access to certain devices, the results can be empty. However, in the /measurement/measurements/series endpoint (see below) the source parameter is required, so the access validation is done before any post filtering operation.

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 a “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

HEADERS
Authorization {{auth}}
Host {{hostname}} 
 GET <<url>>/measurement/measurements/series?source=<<sourceID>>&dateFrom=<<startDate>>&dateTo=<<endDate>>

Example response

HEADERS
Content-Type application/json 
HTTP/1.1
200 OK

{
    "values": {...},
    "series": [...],
    "truncated": false
}

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

HEADERS
Authorization {{auth}}
Host {{hostname}} 
GET <<url>>/measurement/measurements/series?series=c8y_AccelerationMeasurement.acceleration&source=<<sourceID>>&dateFrom=<<startDate>>&dateTo=<<endDate>>

Example response

HEADERS
Content-Type application/json 
HTTP/1.1
200 OK

{
 "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.

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

POST - Create a new measurement

Request body: application/vnd.com.nsn.cumulocity.measurement+json;ver=…

Response body: application/vnd.com.nsn.cumulocity.measurement+json;ver=…

Required role: ROLE_MEASUREMENT_ADMIN or owner of source object

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}}
Content-Type application/vnd.com.nsn.cumulocity.measurement+json
Accept application/vnd.com.nsn.cumulocity.measurement+json 
POST <<url>>/measurement/measurements

{
  "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

HEADERS
Content-Type application/vnd.com.nsn.cumulocity.measurement+json;ver=… 
HTTP/1.1
201 Created

{
  "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.

Important: Property names used for fragment and series must not contain whitespaces and the special characters . , * [ ] ( ) @ $. This is required to ensure a correct processing and visualization of measurement series on UI graphs. Also see Cumulocity IoT’s domain model > Inventory > Naming conventions of fragments in the Concepts guide.

POST - Create multiple measurements

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}}
Content-Type application/vnd.com.nsn.cumulocity.measurementcollection+json
Accept application/vnd.com.nsn.cumulocity.measurementcollection+json 
POST <<url>>/measurement/measurements

{
"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:

HEADERS
Content-Type application/vnd.com.nsn.cumulocity.measurementcollection+json;ver=… 
HTTP/1.1
201 Created

{
 "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:

Parameter Type Description Example
dateFrom string <date-time> Start date or date and time of the measurement. dateFrom=2020-03-01
dateTo string <date-time> End date or date and time of the measurement. dateFrom=2020-03-30
fragmentType string A characteristic which identifies a managed object or event, e.g. geolocation, electricity sensor, relay state. fragmentType=c8y_IsDevice
source string The managed object ID to which the measurement is associated. source=251994
type string The type of measurement to search for. type=c8y_Water

Request body: N/A

Response body: N/A

Required role: ROLE_MEASUREMENT_ADMIN

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}} 
 DELETE: <<url>>/measurement/measurements...

Example response 

HTTP/1.1  
204 NO CONTENT

Info: DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when the deleted measurement has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested measurement is deleted after all associated data has been deleted.

Measurement

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

Name Type Occurs Description POST
id string 1 Uniquely identifies a measurement. No
self string 1 A URI linking to this resource. No
time string 1 Time of the measurement. Mandatory
type string 1 The most specific type of this entire measurement. Mandatory
source ManagedObject 1 The ManagedObject which is the source of this measurement, as object containing the properties “id” and “self”. Mandatory
* array 0..n List of measurement fragments. Optional

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:

Name Type Occurs Description POST
value Any number 1 The value of the individual measurement. The maximum precision for floating point numbers is 64-bit IEEE 754. For integers it’s a 64-bit two’s complement integer. Mandatory
unit string 1 The unit of the measurement, such as “Wh” or “C”. Optional

GET - Representation of a Measurement

Response body: application/vnd.com.nsn.cumulocity.measurement+json;ver=…

Required role: ROLE_MEASUREMENT_READ

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}} 
GET <<url>>/measurement/measurements/<<measurementId>>

Example response

HEADERS
Content-Type application/vnd.com.nsn.cumulocity.measurement+json;ver=… 
HTTP/1.1
200 OK

{
  "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 - 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

HEADERS
Authorization {{auth}}
Host {{hostname}} 
DELETE <<url>>/measurement/measurements/<<measurementID>>

Example Response 

HTTP/1.1
204 NO CONTENT

Info: DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when the deleted measurement has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested measurement is deleted after all associated data has been deleted.

Data streaming

The measurement collection API allows to fetch data in form of a data stream. The response format stays the same but the data is transmitted by the server directly from the database element by element so it can be received in the same way.

Using stream JSON parsers like java json or javascript json parsers we are able to transmit high data volumes in a single request. To activate streaming you need to send as Accept header application/json-stream.

Example

HEADERS
Authorization {{auth}}
Host {{hostname}}
Accept application/json-stream 
GET <<url>>/measurement/measurements

Other response formats

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

Sample CSV response:

time,source,device_name,fragment.series,value,unit
2020-03-15T17:03:14.000+02:00,424,testAgent,c8y_TemperatureMeasurement.T,37,C

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 Real-time notifications. The URL is

/cep/realtime

The subscription channel needs to contain the managed object ID of the device or an asterisk (*) as placeholder to receive notifications for the measurements of all devices.

/measurements/<<deviceId>>

In addition to the measurement object, the response will 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.

Required role: ROLE_MEASUREMENT_READ

Example response

HEADERS
Content-Type application/json 
HTTP/1.1
200 OK

[
  {
    "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"
  }
]