Sinasens user guide - Technical documentation on Sirea Docs

Last update on 20/10/2022 21:33

1. Introduction
- 1.1 Targeted users
2. Application overview
3. API

1. Introduction

1.1 Targeted users

This documentation is intended for users of the Sinasens application, allowing the visualization of the data provided by the Sinafis sensors.

2. Application overview

Coming soon …

3. API

3.1 Obsolescence

The version 1 of the API will is longer accessible since October 31, 2019. It is imperative to migrate to version 2 of the API to be able to continue using your applications beyond this date.

3.2 Overview

Most of the data on the Sinasens site is accessible via programming an API webservice. API requests are used to interface with various software and programming languages. This API uses the https protocol.

Some API functions return data either in JSON format or in CSV format depending on the option chosen.

API functions are subject to change. As far as possible, compatibility with the previous functions will be maintained. Likewise, new functions can be created to enrich the functionality of the API.

The base address for accessing the API v2 is :

https://www.sinasens.com/api/v2/

3.3 Terms of use

The API can be used to occasionally retrieve data accessible by the sinasens.com site.

It must in no case be used to retrieve events in “polling” mode at too high a frequency (greater than once per hour). The risk is that you will get a code 429 “too many requests”.

3.4 Authentication and security

The API is currently only accessible via the HTTPS protocol. All requests require the use of an API key consisting of an identifier (login) and a password (password). This information is confidential. They can be sent by email by logging into your account on https://www.sinasens.com and selecting « My Account -> Get my API key ».

This key is unique. You are the sole owner and you must insure its confidentiality. If you wish to obtain a new key you must request it by sending an email to support.sinasens@sinafis.com from your email account that servers as your Login ID on sinasens.com. If a new key is generated, the old one is irretrievably destroyed and can no longer be used.

3.5 HTTP return codes

The SinaSens API only returns a limited number of HTTP codes:

200: the request was correctly executed.
400: request error. A parameter is missing or invalid.
401: API key missing or invalid (login and / or password).
403: access denied or request not authorized.
404: The resource for the request was not found.
429: too many requests. Request frequency too high.
500: unknown error.

3.6 Name of CSV output file

The format of the output name of the CSV file following a request is composed of the device identification number, the name of the request, the date and time of the file generation:

<device ID>_<request name>_<year>_<month>_<day>_<hours>_<minutes>_<seconds>.csv

For example :

36F9EE_HISTORY_2019_09_8_14_04_23.csv

36F9EE_GPS_2019_09_8_16_23_18.csv

3.7 Fonctions de l’API

3.7.1 API Functions

Query

history.php

Structure

https://www.sinasens.com/api/v2/history.php?login=LOGIN&password=PASSWORD&devic
e=DEVICE&fromDate=FROMDATE&toDate=TODATE&max=MAX&
gps=GPS&mode=MODE

Parameters

Parameter	Comments
LOGIN	Required. API key identifier (ex: c428g2730739in2i23fk23tk).
PASSWORD	Required. API key password (ex: ms7mg0bry06gf7i1hnyf8e9mym6jx58t).
DEVICE	Required. ID number of the Sinasens transmitter whose history you want to retrieve (ex. 36E975).
FROMDATE	Optional. Date and time of the start of the history search. The format is YYYY-MM-DD HH: MM: SS where YYYY represents the year, MM the month, DD the day, HH the time in 24h format, MM the minutes, SS the seconds. If the parameter “fromDate” is omitted, the search will start on the first event found in the history
TODATE	Optional. Date and time of the end of the history search. The format is YYYY-MM-DD HH: MM: SS where YYYY represents the year, MM the month, DD the day, HH the time in 24h format, MM the minutes, SS the seconds. If the parameter “toDate” is omitted, the search will end on the last event found in the history.
MAX	Optional. Maximum number of events to return. If the parameter “max” is omitted or if max = 0, all events found in the search period will be returned.
GPS	Optional. Option to return GPS position information from the device. 1 -> GPS positions will be returned in history, 0 -> GPS positions will not be returned in history. If the parameter “gps” is omitted, the GPS positions will not be returned in the history.
MODE	Optional. Format in which data is returned. There are 2 possible formats: JSON or CSV. If the parameter “mode” is omitted, the output format is CSV.

Query output parameters (CSV or JSON)

Parameter CSV	Parameter JSON	Comments
DATE_UNIX	dateUnix	Date of the event expressed in number of seconds since January 1, 1970 at midnight UTC.
DATE	date	Date of the event in the form dd/mm/ yyyy UTC.
HEURE	heure	Time of the event in the form hh:mm:ss.
ID	device	Sinasens transmitter number.
LATITUDE	latitude	Latitude in decimal degrees (positive value for North and negative for South). Null if the event is not linked to a GPS string.
LONGITUDE	longitude	Longitude in decimal degrees (positive value for East and negative for West). Null if the event is not linked to a GPS string.
TEMP1	temp1	Temperature of sensor 1 in degrees Celsius (-120 ° C to + 120 ° C). Null if the sensor does not exist or if no value is measured.
HUM1	hum1	Humidity of sensor 1 in % (0 to 100%). Null if the sensor does not exist or if no value is measured.
TEMP2	temp2	Temperature of sensor 2 in degrees Celsius (-120 ° C to + 120 ° C). Null if the sensor does not exist or if no value is measured.
HUM2	hum2	Humidity of sensor 2 in % (0 to 100%). Null if the sensor does not exist or if no value is measured.
TEMP3	temp3	Temperature of sensor 3 in degrees Celsius (-120 ° C to + 120 ° C). Null if the sensor does not exist or if no value is measured.
HUM3	hum3	Humidity of sensor 3 in % (0 to 100%). Null if the sensor does not exist or if no value is measured.
TEMP4	temp4	Temperature of sensor 4 in degrees Celsius (-120 ° C to + 120 ° C). Null if the sensor does not exist or if no value is measured.
HUM4	hum4	Humidity of sensor 4 in % (0 to 100%). Null if the sensor does not exist or if no value is measured.
TENSION	tension	Battery voltage at the time of transmission in volts.
SIGNAL	signal	Quality of the radio signal of the transmitted string (0 to 4). 0 = limit, 1 = average, 2 = good, 3 = very good, 4 = excellent

Example of query in JSON format

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&gps=1&max=5&mode=json

Example of response in JSOn format

[
 {
  "dateUnix":"1608585027",
  "date":"21\/12\/2020",
  "heure":"22:10:27",
  "device":"36E975",
  "latitude":null,
  "longitude":null,
  "temp1":"21.4",
  "hum1":"51",
  "temp2":null,
  "hum2":null,
  "temp3":null,
  "hum3":null,
  "temp4":null,
  "hum4":"100",
  "tension":"3.5",
  "signal":"1"
 },
 {
  "dateUnix":"1608584997",
  "date":"21\/12\/2020",
  "heure":"22:09:57",
  "device":"36E975",
  "latitude":"43.584362030029",
  "longitude":"1.8461133241653",
  "temp1":null,
  "hum1":null,
  "temp2":null,
  "hum2":null,
  "temp3":null,
  "hum3":null,
  "temp4":null,
  "hum4":null,
  "tension":"3.3",
  "signal":"1"
 },
 {
  "dateUnix":"1608582702",
  "date":"21\/12\/2020",
  "heure":"21:31:42",
  "device":"36E975",
  "latitude":null,
  "longitude":null,
  "temp1":"21.9",
  "hum1":"51",
  "temp2":null,
  "hum2":null,
  "temp3":null,
  "hum3":null,
  "temp4":null,
  "hum4":"55",
  "tension":"3.5",
  "signal":"1"
 },
 {
  "dateUnix":"1608582673",
  "date":"21\/12\/2020",
  "heure":"21:31:13",
  "device":"36E975",
  "latitude":"43.584609985352",
  "longitude":"1.8463567495346",
  "temp1":null,
  "hum1":null,
  "temp2":null,
  "hum2":null,
  "temp3":null,
  "hum3":null,
  "temp4":null,
  "hum4":null,
  "tension":"3.3",
  "signal":"1"
 },
 {
  "dateUnix":"1583140366",
  "date":"2\/03\/2020",
  "heure":"10:12:46",
  "device":"36E975",
  "latitude":null,
  "longitude":null,
  "temp1":"22.3",
  "hum1":"54",
  "temp2":null,
  "hum2":null,
  "temp3":null,
  "hum3":null,
  "temp4":null,
  "hum4":null,
  "tension":"3.5",
  "signal":"4"
 }
]

Example of query in CSV format

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&gps=1&max=5&mode=csv

Example of response in CSV format

DATE_UNIX;DATE;HEURE;ID;LATITUDE;LONGITUDE;TEMP1;HUM1;TEMP2;HUM2;TEMP3;HUM3;TEMP4;HUM4;TENSION;SIGNAL
1608585027;21/12/2020;22:10:27;36E975;;;21.4;51;;;;;;100;3.5;1
1608584997;21/12/2020;22:09:57;36E975;43.584362030029;1.8461133241653;;;;;;;;;3.3;1
1608582702;21/12/2020;21:31:42;36E975;;;21.9;51;;;;;;55;3.5;1
1608582673;21/12/2020;21:31:13;36E975;43.584609985352;1.8463567495346;;;;;;;;;3.3;1
1583140366;2/03/2020;10:12:46;36E975;;;22.3;54;;;;;;;3.5;4

Examples of history queries

The last 15 events for the device 36F9EE without the GPS

CSV:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=15

JSON:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=15&mode=json

All the events for the device 36F9EE from May 1, 2019 and May 2, 2019

CSV:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&fromDate='2019-05-01'&toDate='2021-05-02'&gps=1

JSON:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&fromDate='2019-05-01'&toDate='2021-05-02'&gps=1&mode=json

The last 36 events for the device 36F9EE on August 12, 2019 between 8:04 am and 2:22:18 pm without GPS:

CSV:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&fromDate='2019-08-12 08:04:00'&toDate='2019-08-12 14:22:18'

JSON:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&fromDate='2019-08-12 08:04:00'&toDate='2019-08-12 14:22:18'&mode=json

All the events of the device 36F9EE for the month of June 2019 with GPS

CSV:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&fromDate=’2019-06’&toDate=’2019-07’&gps=1

JSON:

https://www.sinasens.com/api/v2/history.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&fromDate=’2019-06’&toDate=’2019-07’&gps=1&mode=json

3.7.2 GPS position of a device

Query

gps.php

Structure

https://www.sinasens.com/api/v2/gps.php?login=LOGIN&password=PASSWORD&device=
DEVICE&max=MAX&mode=MODE

Parameters

Parameter	Comments
LOGIN	Required. API key (ex. c428g2730739in2i23fk23ts).
PASSWORD	Required. API password (ex. ms7mg0bry06gf7i1hnyf8e9mym6jx58a).
DEVICE	Required. ID number of the Sinasens transmitter for which you want the historical data (ex. F6F2F).
MAX	Optional. Maximum number of events to return. If the “max” parameter is omitted or if max = 0, all events found in the search period will be returned.
MODE	Optional. Format in which data is returned. There are 2 possible formats: JSON or CSV. If the “mode” parameter is omitted, the output format is CSV.

Query output parameters (CSV or JSON)

Parameter CSV	Parameter JSON	Comments
DATE_UNIX	dateUnix	Date of the event expressed in number of seconds since January 1, 1970 at midnight UTC.
DATE	date	Date of the event in the form dd / mm / yyyy UTC.
HEURE	heure	Time of the event in the form hh:mm:ss.
ID	device	Sinasens transmitter number.
LATITUDE	latitude	Latitude in decimal degrees (positive value for North and negative for South). Null if the event is not linked to a gps string.
LONGITUDE	longitude	Longitude in decimal degrees (positive value for East and negative for West). Null if the event is not linked to a gps string.

Example of query in JSON format

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=2&mode=json

Example of response in JSON format

[
 {"dateUnix":"1608584997",
  "date":"21\/12\/2020",
  "heure":"22:09:57",
  "device":"36E975",
  "latitude":"43.584362030029",
  "longitude":"1.8461133241653"
 },
 {
  "dateUnix":"1608582673",
  "date":"21\/12\/2020",
  "heure":"21:31:13",
  "device":"36E975",
  "latitude":"43.584609985352",
  "longitude":"1.8463567495346"
 }
]

Example of query in CSV format

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=5&mode=csv

Example of response in CSV format

DATE_UNIX;DATE;HEURE;ID;LATITUDE;LONGITUDE
1608584997;21/12/2020;22:09:57;36E975;43.584362030029;1.8461133241653
1608582673;21/12/2020;21:31:13;36E975;43.584609985352;1.8463567495346
1561559348;26/06/2019;16:29:08;36E975;43.58406829834;1.8466166257858

Examples of GPS position queries

The last known GPS position of the device 36F9EE

CSV:

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=1

JSON:

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=1&mode=json

The last 5 GPS positions known for the device 36F9EE

CSV:

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=5

JSON:

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&max=5&mode=json

All known GPS positions of the device 36F9EE

CSV:

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t

JSON:

https://www.sinasens.com/api/v2/gps.php?device=36E975&login=c428g2730739in2i23fk23tk&password=ms7mg0bry06gf7i1hnyf8e9mym6jx58t&mode=json

doc.pdf

Need help?

Our team supports you and can answer all your questions.

Contact support