SmartSense API: Data API
SmartSense provides a set of endpoints for gathering asset and sensor data programmatically. SmartSense organizes devices, sensors, and their readings into logical units referred to as assets. Let’s go over some definitions below.
Definitions
-
Asset – An asset is a logical abstraction of something that is being monitored. A common example is a fridge or a freezer.
-
Sensor Reading – A sensor reading is a figure or amount of data that is based on input from a sensor, such as information related to temperature or humidity.
-
Sensor Point – A sensor point is a logical abstraction for what is being monitored. A fridge asset, for example, could have a temperature and a humidity sensor point.
Sensor points cannot be moved between assets and can only have one sensor associated with it at a time.
-
Sensor – A sensor is a device that measures physical occurrences such as the current temperature or humidity. At SmartSense, a sensor gets attached to a sensor point to link its data to an asset.
A sensor is also attached to a singular device, never more than one.
Example: A store has a fridge and an asset in SmartSense. The temperature and humidity in the fridge must be monitored, so the asset has two sensor points, one for temperature and one for humidity.
Inside the fridge is a device with a temperature and humidity sensor attached. At SmartSense, these sensors get linked with the asset's sensor points. If the Device in the fridge gets replaced with a new device and sensors, the new sensors would be associated with the same sensor points on the asset in SmartSense.
Querying the readings for the fridge's sensor points would show the readings from the first set of sensors for the times when they were attached to the sensor points, and the new sensors after being attached.
- Device – Devices communicate data from the sensors to the SmartSense cloud, and a sensor must be connected to a device to properly measure a reading.
Data Specific Types
The SmartSense Data API defines the following types:
Dates
Parameters of type date should be sent to (and are sent from) the service as a combined date and time in ISO 8601 format. Time zone information must be included or the results of the API call are not defined.
Note: All dates returned by the service are in UTC.
readingDate
readingDate specifies the point in time a reading was captured by a sensor or device, e.g., a temperature sensor recorded a temperature of 32.45°F on Friday, January 15th at 3:17 pm, UTC.
processedDate
processedDate specifies the point in time when a reading was processed by SmartSense.
Example: An external temperature sensor, attached to a device, records a temperature of 32.45°F on Friday, January 15th at 3:17 pm, UTC. Due to an interruption in cellular service, the device is unable to send the reading to SmartSense for five minutes. Thus, the reading would have a readingDate of 3:17 pm, but a processedDate of 3:22 pm.
Applications using this API to capture all readings processed by SmartSense should use the processedAfterDate filter to request new readings since the last request (see Synchronizing Readings).
lastActivityDate
lastActivityDate specifies the time a device or sensor last contacted SmartSense. If the device has never contacted SmartSense this field will be null.
Numbers
DeviceId
The deviceId field is a 20-digit number that is converted to a string and transmitted. It is converted to a string to ease interoperability.
Power Reading Values
A device reading type of Power indicates the status of a device's power source. Values range from 0 to 10 for battery-only devices (e.g., Z-Point Wireless Sensor). For AC-powered devices with battery backup, the values range from 16 to 26 when the device is plugged in and 0 to 10 when not plugged in. A value of 16 indicates AC power only while a value higher than 16 would indicate AC power plus some battery backup.
Signal Strength Reading Values
A device reading type of Signal Strength is a normalized status of a device's wireless signal. Values range from 1-10.
IncidentSeverity
IncidentSeverity describes how severe an Incident or alarm is. An Incident's severity is always equal to the highest severity of any alarm associated with the Incident. An alarm's severity is always equal to the severity configured on the configured alarm that created it. This type has 5 values:
1: Lowest
2: Low
3: Medium
4: High
5: Highest
IncidentStatus
IncidentStatus describes the status of an incident. These values can be updated by the system as new readings come in that resolve or retrigger alarms or by users interacting with incidents in the UI. This type has 4 values:
0: New
1: Active
2: On Hold
99: Closed
The New status means the system has created the incident, but no user action has been taken. Active indicates a user has been assigned to the incident. On Hold is functionally the same as Active, with the addition that a user has selected to put the incident on hold in the UI. Closed means the incident is resolved and will no longer be used by the system; this means that new reading violations will result in new incidents being created.
AlarmStatus
AlarmStatus describes the status of an alarm. An incident can have many alarms so their status is tracked separately per alarm. This type has 4 values:
0: Closed
1: Open
2: Acknowledged
3: Resolved
The Closed status means the system will no longer take any actions with the alarm. New reading violations will result in new alarms. The Open status means the alarm is active. The current reading is out of range and the alarm is available for user action. Acknowledged is the same as Open, with the addition of indicating that a user acknowledged the alarm in the UI. A Resolved alarm means the readings have come back in range.
ViolationOperator
ViolationOperator describes the relational operator used to compare an incoming reading against an alarm threshold. All incidents and alarms are created by the system by comparing readings gathered by sensors to configured alarm thresholds. These thresholds consist of a value and comparison operator, which are also tracked in the alarm instance. This type has 3 values:
-1: Less Than
0: Equal To
1: Greater Than
ThresholdType
ThresholdType describes the type of readings that an alarm is set up or triggered. Each incident will only track alarms for one type of reading. As an example, consider an asset with both temperature and humidity sensors that has two configured alarms: one for temperature and one for humidity. If both sensors go out of range for their respective configured alarm, two incidents (one per reading type) will be created. The type of reading that each incident is responsible for is tracked with this ThresholdType enumeration. The possible values for this type are:
1: Temperature
2: Missed Report
3: Humidity
4: Power
5: Wind Speed
6: Soil Moisture
7: Flood
8: Voltage
9: Pressure
10: Pressure Pascal
11: Leaf Wetness
12: Rainfall
13: Percent CO2
14: Percent O2
15: OLPHC Pressure
16: Dry Contact
17: CentiPascal Pressure
18: Power Low Battery
20: Starwatch Pressure
21: Starwatch Level
23: Pressure KiloPascal
24: Current MilliAmp
25: Current Amp
26: Charge
27: Level
28: Capacitance PicoFarad
99: Validation
Enums
Enums are variable types that have a limited set of values, and fields that are enums are returned as strings in JSON. The string value will be limited to the possible enum values as defined for the type. All enum types have the possibility of being null.
ReadingType
Specifies the type of reading.
Values:
- "Temperature"
- "Humidity"
- "Power"
- "Signal Strength"
Unit
Specifies the unit of a reading.
Values:
- "F"
- "C"
- "%"
DeviceType
Specifies the type of device.
Values:
- "Node"
- "Repeater"
- "Gateway"
SensorType
Specifies the type of sensor.
Values:
- "Temperature"
- "Humidity"
List of IDs
Results Paging
Results paging is a method of separating multiple search results into individual pages to make the information more comprehensive, to not overwhelm the service, and to mitigate time-out issues. Paging also helps limit responses so that the entire data set isn't pulled with each request. Many of the endpoints that return a list of data are subject to paging.
Paged responses include the following paging information:
| Name | Type | Description |
| totalCount | integer (32 bit) | The total number of items found for the request. |
| pageSize | integer (32 bit) | The maximum number of items that could be returned in this response. |
| count | integer (32 bit) | The actual number of items that were returned in this response. |
| pageNumber | integer (32 bit) |
The current page number. This number is 1 indexed. |
If there is an additional page, a link to the next page is specified in the HTTP response header called next. This header may include default values for non-required GET parameters that were not specified in the original request, so this header is preferred over manually creating the URI for your next page to guarantee correct results.
The default pageSize can be overridden by setting a pageSize query parameter:
| Name | Location | Type | Required | Description |
|
pageSize |
query string | integer (32 bit) | no | Set the desired page size for results. Default is 50. The maximum is 1000. |
| pageNumber | query string | integer (32 bit) | no | Set the desired page number. Default is 1. As stated above, the recommendation is to use the next response header when pulling multiple pages. |
Group
The /group endpoints can be used to retrieve information about the group hierarchy in an account.
Get One Group
GET /data/v1/group/{groupId}
Get the group identified by the group ID.
Parameters are shown below:
| Name | Location | Type | Required | Description |
|
groupID |
path | integer (64 bit) | yes | ID of the group to retrieve. |
Output Fields are shown below:
| Name | Type | Description |
| groupId | integer (64 bit) | Unique group identifier. |
| address | string (max 100) | The address associated with this group. |
| name | string (max 255) | Name of the group. |
| parentId | integer (64 bit) |
ID of this group's parent, if any, in the group hierarchy. |
| timezone | string (max 50) |
The time zone assigned to the group as a human-readable string. |
| type | GroupType |
This group's type. |
Responses are shown below:
| Code | Description |
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
Get All Groups
This endpoint gets all the groups in the account to which the API client has access. Groups are returned as a flat list. The response may be broken up into pages, requiring multiple requests to retrieve all of the groups in the account.
GET data/v1/group
Parameters shown below:
None.
Output Fields shown below:
| Name | Type | Description |
| groups | array | Array of group data. The structure is the same as Get One Group. |
Responses shown below:
| Code | Description |
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 422 | Unprocessable Entity |
Incident
The /incident endpoint can be used to retrieve information about the incidents in the user's account.
Get Incidents
Get all the Incidents in the account that satisfy the given query parameters.
GET /data/v1/incident
Parameters shown below:
| Name | Location | Type | Required | Description |
|
assetID |
query string | integer (32 bit) | no | Limit the result set to Incidents involving an Asset, given by its ID. The AssetId parameter is mutually exclusive with the GroupId parameter, both cannot be provided in a single request. |
| groupID | query string | integer (64 bit) | no | Limit the result set to Incidents involving Assets assigned to a Group, given by its ID, or any of its child Groups. The target Group must be a Location or Department Group. The GroupId parameter is mutually exclusive with the AssetId parameter, both cannot be provided in a single request. |
| incidentOpenedStartDate | query string | date | no | Limit the result set to Incidents that were opened after the given Date. Default is 1 hour prior to the request being received by the server. The value cannot be more than 90 days prior to incidentOpenedEndDate |
| incidentOpenedEndDate | query string | date | no | Limit the result set to Incidents that were opened before the given Date. Default is the time the request was received by the server. The value cannot be more than 90 days after the incidentOpenedStartDate |
Output Fields shown below:
| Name | Type | Description |
| incidents | array | Array of Incident Data. |
The Incident Data structure is as follows:
| Name | Type | Description |
| incidentId | integer (64 bit) | The ID of the Incident object. |
| assetId | integer (32 bit) | The ID of the Asset the Incident was created for. |
| assignedUserId | integer (32 bit) | The ID of the User currently assigned to the Incident. |
| automaticallyClosed | boolean |
Indicates whether the Incident was automatically closed by the system. |
| closedDate | date |
The Date the Incident was closed or null if the Incident is still open. |
| deviceId | DeviceId |
The ID of the Device the Incident was created for. |
| openedDate | date |
The Date the Incident was Opened. |
| resolvedDate | date |
The Date all Alarms for the Incident were resolved, or null if there are open Alarms. |
| severity | IncidentSeverity |
The Severity of the Incident. The Incident's severity is always equal to the highest severity of its Alarms. |
| status | IncidentStatus |
The current Status of the Incident. |
| alarms | array |
Array of Alarm Data for the Incident. |
| correctiveActions | array |
Array of Corrective Action data for the Incident. |
The Alarm Data structure is as follows:
| Name | Type | Description |
| dateResolved | date | The Date the Alarm was resolved, or null if is not resolved yet. |
| dateTriggered | date | The Date the Alarm was triggered. |
| name | string | The name of the Configured Alarm that is responsible for triggering the Alarm. |
| readingDate | date |
The Date of the Reading that triggered the Alarm. |
| readingUnit | unit |
Specifies the unit for the readingValue. |
| readingValue | float (64 bit) |
The value of the Reading that triggered the Alarm. |
| severity | IncidentSeverity |
The Severity of the Alarm. |
| status | AlarmStatus |
The current Status of the Alarm. |
| thresholdValue | float (64 bit) |
The value the Alarm was set to trigger at, above, or below. |
| type | ThresholdType |
The current Status of the Incident. |
| ViolationOperator | ViolationOperator |
Array of Alarm Data for the Incident. |
The CorrectiveAction Data structure is as follows:
| Name | Type | Description |
| date | date | The Date the CorrectiveAction was documented. |
| details | string | The message describing the CorrectiveAction. |
| userId | integer (32 bit) | The ID of the User who documented the CorrectiveAction. |
Responses shown below:
| Code | Description |
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 422 | Unprocessable Entity |
Readings
Get Asset Sensor Point Readings
This endpoint gets all readings for the sensors attached to the specified sensor point on the specified asset.
GET /data/v1/readings/asset/{assetId}/sensorpoint/{sensorpointId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
assetId |
path | integer (32 bit) | yes | Unique identifier of the target asset. |
| sensorPointId | path | integer (32 bit) | yes | Unique identifier of the target sensor point. |
| readingStartDate | query string | date | no | Limit the result set to readings with a readingDate greater than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is 1 hour prior to the request being received by the server. |
| readingEndDate | query string | date | no | Limit the result set to readings with a readingDate less than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is the time the request is received by the server. |
| processedAfterDate | query string | date | no | Limit the result set to readings that have been processed after the specified date. If not provided the results are not filtered by processedDate. |
Output fields shown below:
| Name | Type | Description |
| assetId | integer (32 bit) | Unique identifier of the asset. |
| assetName | string (max 50) | The name of the asset. |
| sensorPointId | integer (32 bit) | Unique identifier of the sensor point. |
| sensorPointName | string (max 150) |
The name of the sensor point. |
| readings | array |
Array of readings data. |
The readings data structure is as follows:
| Name | Type | Description |
| sensorId | integer (32 bit) | Unique identifier for the sensor. |
| deviceId | DeviceId | Unique identifier of the device. |
| port | byte | Port number for the sensor (may be null). |
| readingType | Reading Type |
Specifies the type of reading. |
| unit | Unit |
Specifies what unit the reading is being reported in. |
| readingValue | decimal (9.4) |
Reading value. |
| readingDate | date |
Date at which the reading was made. |
| processedDate | date |
Date at which the reading was processed by SmartSense. |
| alarm | boolean |
Indicates if this reading violated an alert threshold configured in SmartSense. |
Responses shown below:
| Code | Description |
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 422 | Unprocessable Entity |
Get Asset Devices’ Readings
This endpoint gets all readings for all the devices attached to the specified asset.
GET /data/v1/readings/asset/{assetId}/devices
Parameters shown below:
| Name | Location | Type | Required | Description |
|
assetId |
path | integer (32 bit) | yes | Unique identifier of the target asset. |
| readingStartDate | query string | date | no | Limit the result set to readings with a readingDate greater than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is 1 hour prior to the request being received by the server. |
| readingEndDate | query string | date | no | Limit the result set to readings with a readingDate less than or equal to the specified date. In all cases, no readings older than 1 year will be returned. Default is the time the request is received by the server. |
| processedAfterDate | query string | date | no | Limit the result set to readings that have been processed after the specified date. If not provided the results are not filtered by processedDate. |
Output fields shown below:
| Name | Type | Description |
| assetId | integer (32 bit) | Unique identifier of the asset. |
| assetName | string (max 50) | The name of the asset. |
| readings | array | Array of readings data. |
The readings data structure is as follows:
| Name | Type | Description |
| deviceId | DeviceId | Unique identifier of the device. |
| readingType | ReadingType | Specifies the type of reading. |
| unit | Unit | Specifies what unit the reading is being reported in. |
| readingValue | decimal (9.4) |
Reading value. |
| readingDate | date |
Date at which the reading was made. |
| processedDate | date |
Date at which the reading was processed by SmartSense. |
| alarm | boolean |
Indicates if this reading violated an alert threshold configured in SmartSense. |
Responses shown below:
| Code | Description |
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 422 | Unprocessable Entity |
Synchronizing Readings
Clients wishing to have their own copy of sensor or device readings can use the processedAfterDate query parameter to stay up to date with SmartSense. Whenever the last "page" of results is returned from a query containing a processedAfterDate value, a header (nextProcessedAfterDate) is included in the response specifying the processedAfterDate value to use on the next query.
Example: Client Alice wants all sensor readings since March 1st, 2021 (UTC), as well as any readings that arrive after that point. Alice will poll SmartSense every 15 minutes using the processedAfterDate query parameter.
To begin, Alice makes the following request:
GET /v1/data/asset/4146/sensorpoint/55689?processedAfterDate="2021-03-01T00:00:00.00Z"
The response from the server may contain several "pages" of data. Each "page" (except the last) will have a header in the response with a link to the next "page." The final "page" will contain a nextProcessedAfterDate header with a datetime value. Alice saves this value as X.
After retrieving all "pages," Alice now has a copy of all sensor readings from the account up to and including the datetime X.
After 15 minutes have passed, Alice queries SmartSense for readings and uses a new value for processedAfterDate: specifically, nextProcessedAfterDate value X from the last "page" of the previous request. SmartSense will respond with any new readings that have arrived since Alice’s last query.
Alice repeats this process every 15 minutes to stay up to date with SmartSense.