Difference between revisions of "FAQ"
(Add link to Sensaphone timestamps on the history page.) |
(→How do I calculate Sensaphone-encoded timestamps?: Add examples) |
||
Line 85: | Line 85: | ||
==How do I calculate Sensaphone-encoded timestamps?== | ==How do I calculate Sensaphone-encoded timestamps?== | ||
+ | Sensaphone timestamps can be calculated using the following formula: | ||
+ | ===Examples=== | ||
+ | ====Bash==== | ||
+ | <syntaxhighlight lang="bash" line='line'> | ||
+ | sensaphone_time() { | ||
+ | local year=$1 | ||
+ | local month=$2 | ||
+ | local day=$3 | ||
+ | local hours=$4 | ||
+ | local minutes=$5 | ||
+ | local seconds=$6 | ||
+ | |||
+ | local sensaphone_timestamp=$(( ( seconds % 60) + | ||
+ | ((minutes * 60) % 3600) + | ||
+ | ((hours * 3600) % 86400) + | ||
+ | ((day * 86400) % 2678400) + | ||
+ | ((month * 2678400) % 32140800) + | ||
+ | (((year % 100) * 32140800)) )) | ||
+ | echo $sensaphone_timestamp | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | ====Python==== | ||
+ | <syntaxhighlight lang="Python" line> | ||
+ | def sensaphone_time(year, month, day, hours, minutes, seconds): | ||
+ | return (seconds % 60) + \ | ||
+ | ((minutes * 60) % 3600) + \ | ||
+ | ((hours * 3600) % 86400) + \ | ||
+ | ((day * 86400) % 2678400) + \ | ||
+ | ((month * 2678400) % 32140800) + \ | ||
+ | ((year % 100) * 32140800) | ||
+ | </syntaxhighlight> | ||
===References=== | ===References=== | ||
* [[Sensaphone.net API/history#Timestamps|Sensaphone-encoded timestamps]]: Info regarding timestamp encoding | * [[Sensaphone.net API/history#Timestamps|Sensaphone-encoded timestamps]]: Info regarding timestamp encoding |
Revision as of 15:01, 17 November 2020
Contents
How do I login?
Overview
To use the Sensaphone REST API, a login call must first be made. A successful login request will return an account number and a session token. These will be used in all subsequent requests. Two examples of login requests are shown below. First, the URI-mode version, followed by the JSON-mode version.
Examples
URI-mode:
GET https://rest.sensaphone.net/api/v1/login/{[email protected]}/{abc123_my_password}
JSON-mode:
POST https://rest.sensaphone.net/api/v1/login { "request_type": "create", "resource": "login", "user_name": "[email protected]", "password": "abc123_my_password" }
Reply
The reply to a successful login request will contain a result object and a response object. The result communicates the overall success of the call. The response contains the data in which we are interested: in this case, the account number (acctid), and the session token. The account number and session token will be used in every subsequent query submitted to the API.
{ "result": { "success": true, "code": 0, "message": "Success" }, "response": { "acctid": 21620750, "session": "1234ffffeeee5678aaaccda609cd8fb5099", "login_timestamp": 1605562465, "session_expiration": 86400, "user_id": 12345678 } }
References
- Login Resource: Additional information about the login resource
- URI-mode/JSON-mode: Information about URI-mode and JSON-mode
How do I access log data?
Overview
Queries to our logging facilities are one of the most popular uses of the Sensaphone API. Making a successful log query involves first acquiring multiple pieces of data from the API. Because of this fact, crafting your first log query will be a multi-step process. All logs are accessed through the history resource. Outlined below you will find a practical example of how to gather the data needed to make a successful query to the history resource.
Examples
Datalog
Every device (e.g. Sentinel, Sentinel Pro, Stratus) associated with your account has input zones to which sensors may be connected. A device may be configured to log the value of any input zone at specific intervals. On www.sensaphone.net (the Website) the user may query a time range of datalog records for a single device. Users of the REST API can make similar queries against the input zones of one or more devices.
The data required to perform a datalog query are defined as follows:
- log_points/data_log_points
- List of one or more unique numeric ID's, each representing a "loggable" device zone.
- begin_offset
- The offset of the first record to be returned to the caller. An offset of 0 indicates the beginning of the queried timerange. Increasing this offset by 5 means we return results beginning with the fifth record obtained by the query. Use this value to "page" through results in descending order, newest to oldest.
- record_offset
- Number of results to return per "page".
- start
- The greatest Sensaphone-encoded timestamp we are interested in. See below for more details about how this value may be calculated.
- end
- The least Sensaphone-encoded timestamp we are interested in. See below for more details about how this value may be calculated.
We will take the following steps to retrieve the information necessary for a query to the datalog facility:
- Get a list of devices associated with an account
- Get a list of log_points from a device
- Calculate Sensaphone-encoded start and end timestamps
- Query for datalog records
For the remainder of this example, let's assume the following:
acctid = 12345678 # account_id session = 1234aaa5678bbbb8765cccc4321dddd # session token
List Devices
First let's list all devices associated with our account and choose one from the results.
POST https://www.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/device
Under the response object in the reply from the server is an array of devices. The device_id is listed in this information.
List Log Points
With a device_id in hand, we may now query for log_points associated with that device. Let's assume our device_id is 9191.
GET https://www.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/history/data_log_points/resource_type/{device}/device_id/{9191}
The server's reply will contain data for each loggable zone, including input zones and output zones. The log_point value of each zone is unique across all devices. Therefore a log_point value of 78208181 will refer to one, and only one, zone. Extract log_point values for all zones to be queried.
Query Datalogs
With start and end
References
How do I calculate Sensaphone-encoded timestamps?
Sensaphone timestamps can be calculated using the following formula:
Examples
Bash
sensaphone_time() {
local year=$1
local month=$2
local day=$3
local hours=$4
local minutes=$5
local seconds=$6
local sensaphone_timestamp=$(( ( seconds % 60) +
((minutes * 60) % 3600) +
((hours * 3600) % 86400) +
((day * 86400) % 2678400) +
((month * 2678400) % 32140800) +
(((year % 100) * 32140800)) ))
echo $sensaphone_timestamp
}
Python
def sensaphone_time(year, month, day, hours, minutes, seconds):
return (seconds % 60) + \
((minutes * 60) % 3600) + \
((hours * 3600) % 86400) + \
((day * 86400) % 2678400) + \
((month * 2678400) % 32140800) + \
((year % 100) * 32140800)
References
- Sensaphone-encoded timestamps: Info regarding timestamp encoding