Data points

Data points are sensors connected to your Collactr devices — they allow you to store and monitor incoming device sensor values.

Properties

  • Name
    sensorName
    Type
    string
    Description

    Unique identifier for the data point.

  • Name
    displayName
    Type
    string
    Description

    The display name for the data point.

  • Name
    sensorType
    Type
    string
    Description

    The type of data point, which defines and normalizes the data.

  • Name
    currentValue
    Type
    string | integer
    Description

    The current value of the data point.

  • Name
    rawValue
    Type
    string | integer
    Description

    An unformatted version of the current value of the data point.

  • Name
    currentStatus
    Type
    boolean
    Description

    The status that this is linked to this data point. This can be: INFO, WARNING, ERROR or CRITICAL.

  • Name
    units
    Type
    string
    Description

    A prefix/suffix for this data point, based on the sensorType.

  • Name
    timeSinceLastSuccessUTC
    Type
    timestamp
    Description

    Timestamp of when this data point was last in a 'SUCCESS' status.

  • Name
    timeSinceCurrentStatusUTC
    Type
    timestamp
    Description

    Timestamp of when this data point was first in it's current status.

  • Name
    updatedUTC
    Type
    timestamp
    Description

    Timestamp of when this data point was last updated.

POST/sensors/list

List data points

This endpoint allows you to retrieve a list of all the data points for a specific Collactr device.

Required attributes

  • Name
    deviceName
    Type
    string
    Description

    The name of the device that you want to list data points for.

Request

POST
/sensors/list
curl -G https://api.collactr.com/sensors/list \
  -H "Authorization: Bearer {token}"
  -d '{"deviceName": "device_1_hallway"}'

Response

{
  "status": "success",
  "data": [
    {
      "sensorName": "Temperature",
      "displayName": "Temperature",
      "sensorType": "tempC",
      "currentValue": "19,2 °C",
      "rawValue": 19.2,
      "suppressed": false,
      "currentStatus": "SUCCESS",
      "lastSuccessAt": "2023-02-18T09:21:21.000Z",
      "currentSuccessAt": "2023-02-18T08:57:21.000Z",
      "updatedAt": "2023-02-18T09:21:21.000Z",
      "units": " °C"
    },
    ... // more data points
  ]
}
POST/sensors/details

List data point details

This endpoint allows you to retrieve all details for a specific data point of a Collactr device.

Required attributes

  • Name
    deviceName
    Type
    string
    Description

    The name of the device that you want to retrieve data for.

  • Name
    sensorName
    Type
    string
    Description

    The name of the data point that you want to retrieve details for.

Request

POST
/sensors/list
curl -G https://api.collactr.com/sensors/details \
  -H "Authorization: Bearer {token}"
  -d '{"deviceName": "device_1_hallway, "sensorName": "Battery"}'

Response

{
  "status": "success",
  "data": {
    "sensorName": "Battery",
    "displayName": "Battery",
    "sensorType": "milliVolts",
    "currentValue": "3.543 mV",
    "rawValue": 3543,
    "suppressed": false,
    "currentStatus": "SUCCESS",
    "timeSinceLastSuccessUTC": "2023-02-18T09:17:21.000Z",
    "timeSinceCurrentStatusUTC": "2022-10-16T11:43:11.000Z",
    "updatedUTC": "2023-02-18T09:17:21.000Z",
    "units": " mV",
    "last24Hours": [
      {
        "sUTC": 1613556000,
        "eUTC": 1613559599,
        "count": 15,
        "total": 53145,
        "max": 3545,
        "min": 3541,
        "avg": 3543
      },
      {
        "sUTC": 1613559600,
        "eUTC": 1613563199,
        "count": 15,
        "total": 53145,
        "max": 3542,
        "min": 3544,
        "avg": 3543
      },
      ... // and more data
    ]
  }
}
POST/sensors/batchList

Bulk list data points

This endpoint allows you to retrieve data point information for multiple Collactr devices by supplying the names of the devices in an array format.

Required attributes

  • Name
    devices
    Type
    array
    Description

    A comma seperated list of device names that you want to retrieve data points for.

Request

POST
/sensors/batchList
curl -G https://api.collactr.com/sensors/batchList \
  -H "Authorization: Bearer {token}"
  -d '{"devices": ["device_1_hallway", "device_2_rd_office"]}'

Response

{
  "status": "success",
  "data": [
    {
      "deviceName": "device_1_hallway",
      "sensors": [
        {
          "sensorName": "Temperature",
          "displayName": "Temperature",
          "sensorType": "tempC",
          "currentValue": "19,2 °C",
          "rawValue": 19.2,
          "suppressed": false,
          "currentStatus": "SUCCESS",
          "timeSinceLastSuccessUTC": "2023-02-18T09:21:21.000Z",
          "timeSinceCurrentStatusUTC": "2023-02-18T08:57:21.000Z",
          "updatedUTC": "2023-02-18T09:21:21.000Z",
          "units": " °C"
        },
        ... // more data points
      ]
    },
    {
      "deviceName": "device_2_rd_office",
      "sensors": [
        {
          "sensorName": "Temperature",
          "displayName": "Temperature",
          "sensorType": "tempC",
          "currentValue": "19,2 °C",
          "rawValue": 19.2,
          "suppressed": false,
          "currentStatus": "SUCCESS",
          "timeSinceLastSuccessUTC": "2023-02-18T09:21:21.000Z",
          "timeSinceCurrentStatusUTC": "2023-02-18T08:57:21.000Z",
          "updatedUTC": "2023-02-18T09:21:21.000Z",
          "units": " °C"
        },
        ... // more data points
      ]
    }
  ]
}
POST/sensors/batchDetails

Bulk list data point details

This endpoint allows you to retrieve detailed information about data points for multiple devices at the same time by supplying the names of the devices and data points in an array format.

Required attributes

  • Name
    sensors
    Type
    array
    Description

    A comma seperated list of device and data points names that you want to retrieve details for.

Request

POST
/sensors/batchDetails
curl -G https://api.collactr.com/sensors/batchDetails \
  -H "Authorization: Bearer {token}"
  -d '{"sensors": [{"deviceName":"device_1_hallway","sensorName":"Humidity"}, {"deviceName":"device_2_rd_office","sensorName":"Light"}]}'

Response

{
  "status": "success",
  "data": [
    {
      "deviceName": "device_1_hallway",
      "sensors": [
        {
          "sensorName": "Humidity",
          "displayName": "Humidity",
          "sensorType": "relativeHumidity",
          "currentValue": "43% RH",
          "rawValue": 43,
          "suppressed": false,
          "currentStatus": "SUCCESS",
          "timeSinceLastSuccessUTC": "2023-02-18T09:21:21.000Z",
          "timeSinceCurrentStatusUTC": "2023-02-18T09:01:21.000Z",
          "updatedUTC": "2023-02-18T09:21:21.000Z",
          "units": "% RH"
        }
      ]
    },
    {
      "deviceName": "device_2_rd_office",
      "sensors": [
        {
          "sensorName": "Light",
          "displayName": "Light",
          "sensorType": "lux",
          "currentValue": "126 LUX",
          "rawValue": 126,
          "suppressed": false,
          "currentStatus": "SUCCESS",
          "timeSinceLastSuccessUTC": "2023-02-18T09:21:21.000Z",
          "timeSinceCurrentStatusUTC": "2022-10-16T11:43:11.000Z",
          "updatedUTC": "2023-02-18T09:21:21.000Z",
          "units": " LUX"
        }
      ]
    }
  ]
}
POST/sensors/export

Export device data

This endpoint allows you to retrieve historic data point information by supplying a device name and a data point name.

Required attributes

  • Name
    deviceName
    Type
    string
    Description

    The name of the device that you want to retrieve data for.

  • Name
    sensorName
    Type
    string
    Description

    The name of the data point that you want to retrieve details for.

Optional attributes

Optionally, you can retrieve data for a specific date range by adding "startUTC" and "endUTC" to the request body, which both take UNIX timestamps (UTC in seconds) as values.

  • Name
    startUTC
    Type
    number | optional
    Description

    UNIX timestamp that defines the start of the data range that you want to retrieve.

  • Name
    endUTC
    Type
    number | optional
    Description

    UNIX timestamp that defines the end of the data range that you want to retrieve.

UNIX timestamps can be created in many programming languages. For example, in JavaScript you can call Math.floor(Date.now() / 1000) to get the current UNIX timestamp in seconds. Manually, they can be created with the help of websites such as https://www.unixtimestamp.com.

Request

POST
/sensors/export
curl -G https://api.collactr.com/sensors/export \
  -H "Authorization: Bearer {token}"
  -d '{"deviceName":"ComfortSensor","sensorName":"Temperature", "startUTC": 1646089200, "endUTC": 1648764000}'

This call is limited to only one use per month, as it requires a lot of resources.