Skip to content

Devices

Retired. This endpoint is no longer available

Use /v2/devices.

GET {baseURl}/v1/devices
Returns a list of devices that the developer has access to, together with metadata and the latest device status.

Example
https://clarity-data-api.clarity.io/v1/devices

Headers

  • x-api-key: the API key string.

Request

query parameter description
org string
optional		 Filter devices by organization. If the API key provided identifies a user who has a role in more than one organization, then the org parameter specifies which org. If the parameter is not provided, then the default is to use the first org for that user.
Find the org ID by clicking on your user icon in Dashboard.
Example "myorgVD43"

Response

attribute description
code string The node ID (marked on the physical device).

Example: "A0000001"
location GeoJSON object The deployed location of the device.
see example below
enabledCharacteristics array All characteristics the device is able to measure. Not guaranteed that all characteristics in the list will be included in a measurement. Hardware failures may result in missing characteristics.
see example below
lifeStage string The life stage of the device.
see Lifestages below
state object The configuration of the device. Configuration is controlled by Clarity support team
See Device State below
photo string The URL of the device's photo.

Example: https://dashboard.clarity.io/static/media/node-s.4fcbbc54.png
indoor bool True = indoors
False = outdoors
roadDistance number Distance from road, in meters
aglHeight number Height above ground level, in meters
workingStartAt string Optional. The time when the device started working.

Example: "2019-01-01T00:00:00.000Z"
lastReadingReceivedAt string Optional. The time when device uploaded the last reading.

Example: "2019-01-01T00:00:00.000Z"
latestBatteryVoltage number Optional. The latest battery voltage, in Volts.

Example: 4.121234
batteryPercentage number Optional. The latest battery charge, as percentage of full

Example: 99.1
batteryStatus string Optional. The health status of battery. The possible values are listed below.
rssi number Optional. RSSI stands for Received Signal Strength Indicator. It is an estimated measure of power level that an RF client device is receiving from an access point. (unit: dBm)

Example: -51
signalStrength string Optional. The quality of signal. The possible values are
"marginal" < "ok" < "good" < "excellent"
sensorsHealthStatus string Optional. The status of sensors embedded in a device. Possible values are listed below.
overallStatus string Optional. The overall status of a device. Possible values are listed below.


Example GeoJSON object

{
    "coordinates": [
        -122.2687187,  // longitude
        37.8712728     // latitude
    ],
    "type": "Point"
}


Example Characteristics array

"enabledCharacteristics": [
    "relHumid",
    "temperature",
    "pm2_5ConcNum",
    "pm2_5ConcMass",
    "pm1ConcNum",
    "pm1ConcMass",
    "pm10ConcNum",
    "pm10ConcMass",
    "no2Conc"
]

Lifestage

  • "purchased": device belongs to the user's organization but has not been configured yet.
  • configured": device has been configured through Clarity Dashboard but has not uploaded any measurement yet.
  • "working": device has uploaded at least one measurement after being configured. Note that "working" lifestage does not imply that the device is active or has no issues.
  • "decommisioned": device has been deemed no longer usable by Clarity support team.

State (of device)

More configuration information might be added later.

nodeSleepConfig: (object)
- sleepTime: (number) the sleep time in seconds.
- sleepMultiplier: (number) the multiplier of sleep time.

Example 

{
    "state": {
        "nodeSleepConfig": {
            "sleepMultiplier": 1,
            "sleepTime": 900},
    }
}

Battery status

  • normal: Battery is discharging properly.
  • recoveryMode: Very low battery voltage, the device slows down and tries to recover.
  • charging: Battery is charged from solar panel or power adapter.
  • temperatureError: Too low or too high temperature to charge battery, or thermistor issue.
  • readoutError: Cannot read battery.

Sensor health status

  • nominal: No reading out of expected bound, no error codes from sensors.
  • degraded: More than 1 and less than 20 of the last 25 readings are out of bound for any characteristic.
  • critical: More than 20 of the last 25 readings are out of bound for any characteristic, or there is any error code.

Overall status

  • needsSetup: A device needs setup if its life stage is purchased or configured
  • needsAttention: A device needs attention
    • if the server hasn't received its reading for over 48 hours.
    • if its signal strength is marginal.
    • if its sensors health status is critical or degraded.
    • if its battery Status is recoveryMode, temperature Error or readoutError.
    • if its battery percentage is lower than 20%.
  • healthy: This device is working properly.

Example 200 Response

[
    {
        "code": "A0000001",
        "lifeStage": "working",
        "location": {
            "coordinates": [
                -10.8658,
                39.576
            ],
            "type": "Point"
        },
        "enabledCharacteristics": ["pm2_5ConcMass", "pm10ConcMass"],
        "state": {
            "nodeSleepConfig": {"sleepMultiplier": 1, "sleepTime": 900},
        },
        "photo": "https://s3.bucket/photo.jpg",
        "roadDistance": 1,
        "indoor": false,
        "aglHeight": 3,
        "workingStartAt": "2020-01-18T12:05:40.340Z",
        "lastReadingReceivedAt": "2021-01-18T12:05:40.340Z",
        "latestBatteryVoltage": 4.9,
        "batteryStatus": "normal",
        "batteryPercentage": 99.2,
        "signalStrength": "excellent",
        "rssi": -51,
        "sensorsHealthStatus": "nominal",
        "overallStatus": "healthy"
    }
]