Sensaphone.net API/history

Sensaphone.net API

Access

The History API allows access to the Audit Log, the Data Log, and the Event Log

Specifications

The URI Mode for the History API is unique because it allows filtering options to be specified in pairs and can be added in any order. Also, the array values are expressed as a common-separated list.

 /history/audit_log/var_ids/{1234,9876}/changes/{create}

Timestamps

The history APIs such as the Data Log use Sensaphone encoded timestamps. This allows the timestamps to be independent of the time zone of the client request, and return results adjusted to the time zone of the device, account, etc. Seconds, minutes, hours, days, and months are 0-indexed, in other words the range of month values is [0,11]. The year value is 2000-based and limited to 100 years.

In order to create a Sensaphone timestamp given the year, month, day, hours, minutes, and seconds, convert each parameter to its equivalent value in seconds. For the example, in pseudo-code, a factory method would look as following:

getSensaphoneTimestamp( year, month, day, hours, minutes, seconds )  {
 return ((seconds                      % 60)) +
           ((minutes      * 60)        % 3600) +
           ((hours        * 3600)      % 86400) +
           ((day          * 86400)     % 2678400) + 
           ((month        * 2678400)   % 32140800) + 
           ((year % 100   * 32140800));  
 }

Audit Log

Audit Log Filter Options

Property	Status	Type	Description
var_ids	Optional	Array of Integer	list of variable ids
user_ids	Optional	Array of Integer	list of user ids
changes	Optional	Array of String	list of change types ("create","delete","update")
start	Optional	Integer	the start time (Sensaphone timestamp)
end	Optional	Integer	the end time (Sensaphone timestamp)
begin_offset	Optional	Integer	the beginning offset of the first record
record_offset	Optional	Integer	the offset from the beginning

GET

Audit Log Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	String	Session ID
	request_type	String	"read"
	history	Object	The History object
history	audit_log	Object	Audit Log Filter Options

Audit Log Response Properties

Parent Property	Child Property	Type	Description
	history	Object	The history object
history	audit_log	Array of Objects	The returned log
audit_log	change	String	The change that occurred
audit_log	who	String	Who changed it
audit_log	what	String	What changed
audit_log	when	String	When it changed
audit_log	epoch	Integer	The epoch time
history	audit_log_filter	Object	Audit Log Filter Options (Only returned in V2)

• Receive all changes for a variable:
• URI Mode:

 GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/var_ids/{1234}

• JSON Mode:

 POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/

 {
 "request_type": "read",
 "history":
   {
     "audit_log": {
       "var_ids" : [1234]
     }
   }
 }

Data Log

Data Log Filter Options

Property	Status	Type	Description
log_points	Optional	Array of Integer	list of variable ids
status	Optional	Array of String	list of AlarmStatus ("normal", "dependency", "alarm")
start	Optional	Integer	the start time (Sensaphone timestamp)
end	Optional	Integer	the end time (Sensaphone timestamp)
begin_offset	Optional	Integer	the beginning offset of the first record
record_offset	Optional	Integer	the offset from the beginning

GET

Data Log Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	String	Session ID
	request_type	String	"read"
	history	Object	The History object
history	data_log	Object	Data Log Filter Options

Data Log Response Properties

Parent Property	Child Property	Type	Description
	history	Object	The history object
history	data_log	Array of Objects	The returned log
data_log	record_id	String	The id of the record
data_log	value	String	The value of the variable
data_log	variable	String	The variable id
data_log	is_alarm	String	Is an alarm
data_log	epoch	Integer	The epoch time
history	data_log_filter	Object	Audit Log Filter Options (Only returned in V2)

• Receive the last 50 logged datas for a log point
• URI Mode:

 GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log/log_points/{1234}/begin_offset/{0}/record_offset/{50}

• JSON Mode:

 POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log

 {
 "request_type": "read",
 "history":
   {
     "data_log": {
       "log_points" : [1234],
       "begin_offset" : 0,
       "record_offset" : 50
     }
   }
 }

Data Log Points

Poll the Data Log Points to get the possible logable points to use for the Data Log

GET

Data Log Points Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	String	Session ID
	request_type	String	"read"
	history	Object	The History object
history	data_log_points	Object
data_log_points	resource_type	String	the name of the resource, e.g. "device"
data_log_points	(id_name)	Integer	The ID of the resource, e.g. "device_id"

Data Log Points Response Properties

Parent Property	Child Property	Type	Description
	history	Object	The history object
history	data_log_points	Object	The returned log
data_log_points	resource_type	String	the name of the resource, e.g. "device"
data_log_points	(id_name)	Integer	The ID of the resource, e.g. "device_id"
data_log_points	log_points	Array of Objects	The logable points
log_points	category	String	The type of logable point
log_points	(id_name)	Integer	The ID of the resource, e.g. "zone_id"
log_points	log_point	Integer	The logable point ID

• Receive all data logable points for a device:
• URI Mode:

 GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log_points/resource_type/{device}/device_id/{1234}

• JSON Mode:

 POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log_points

 {
 "request_type": "read",
 "history":
   {
     "data_log_points": {
       "resource_type" : "device",
       "device_id" : 1234
     }
   }
 }

Event Log

Event Log Filter Options

Property	Status	Type	Description
contact_ids	Optional	Array of Integer	list of contact ids
device_ids	Optional	Array of Integer	list of device ids
zone_ids	Optional	Array of Integer	list of zone ids
user_ids	Optional	Array of Integer	list of user ids
event_types	Optional	Array of String	list of event types
start	Optional	Integer	the start time (Sensaphone timestamp)
end	Optional	Integer	the end time (Sensaphone timestamp)
begin_offset	Optional	Integer	the beginning offset of the first record
record_offset	Optional	Integer	the offset from the beginning

GET

Event Log Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	String	Session ID
	request_type	String	"read"
	history	Object	The History object
history	event_log	Object	Event Log Filter Options

Event Log Response Properties

Parent Property	Child Property	Type	Description
	history	Object	The history object
history	event_log	Array of Objects	The returned log
event_log	event	String	Which event
event_log	when	String	When it changed
event_log	epoch	Integer	The epoch time
event_log	type	String	The type
event_log	source	Object	The sources of the event
source	<source_name>	String	A source
history	event_log_filter	Object	Event Log Filter Options (Only returned in V2)

• Receive last 50 "Alarms Events" for a device:
• URI Mode:

 GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log/device_ids/{1234}/event_types/{alarm}/begin_offset/{0}/record_offset/{50}

• JSON Mode:

 POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log

 {
 "request_type": "read",
 "history":
   {
     "event_log": {
       "event_types" : ["alarm"],
       "device_ids" : [1234],
       "begin_offset" : 0,
       "record_offset" : 50
     }
   }
 }