Notice Sinasens - Documentation technique sur Sirea Docs

Dernière modification le 20/10/2022 21:24

1. Introduction
- 1.1 Lecteurs ciblés
2. Présentation de l’application
3. API

1. Introduction

1.1 Lecteurs ciblés

Cette documentation est à destination des utilisateurs de l’application Sinasens, permettant de la visualisation de données collectées par les sondes Sinafis.

2. Présentation de l’application

A venir …

3. API

3.1 Obsolescence

L’API v1 est devenue obsolète le 31 octobre 2019. Si vous utilisiez l’API v1, il est impératif que vous effectuez une migration afin de continuer à utiliser les services de Sinasens.

3.2 Généralités

La plupart des données présentes sur le site de SinaSens SmartAgri sont accessibles par un webservice API par programmation. Les requêtes d’API permettent de s’interfacer avec divers logiciels et langages de programmation. Cette API utilise le protocole HTTPS.

Certaines fonctions de l’API retournent les données soit au format JSON, soit au format CSV suivant l’option choisie.

Les fonctions de l’API sont susceptibles d’évoluer. Dans la mesure du possible la compatibilité avec les fonctions précédentes sera conservée. De la même façon, de nouvelles fonctions peuvent être créées pour enrichir les fonctionnalités de l’API.

L’adresse de base pour l’accès à l’API v2 est :

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

3.3 Conditions d’utilisation

L’API peut être utilisée pour récupérer de façon ponctuelle des données accessibles par le site sinasens.com.

Elle ne doit en aucun cas être utilisée pour récupérer des évènements en mode « polling » à une fréquence trop élevée (supérieure à une fois par heure). Le risque est alors d’obtenir en retour un code 429 « trop de requêtes ».

3.4 Authentification et sécurité

L’API est pour l’instant uniquement accessible via le protocole HTTPS. Toutes les requêtes nécessitent l’utilisation d’une clé d’API constituée d’un identifiant (login) et d’un mot de passe (password). Ces informations sont confidentielles. Elles peuvent être transmises par Email en vous connectant à votre compte sur https://www.sinasens.com en sélectionnant « Mon compte -> Obtenir ma clé d’API ».

Cette clé est unique. Vous en êtes le seul propriétaire et vous devez apporter toute l’attention nécessaire à sa confidentialité. Si vous souhaitez obtenir une nouvelle clé vous devez en faire la demande en envoyant un mail à support.sinasens@sinafis.com à partir de votre compte e-mail identifié sur sinasens.com. Il sera prochainement possible de générer cette clé à partir de votre compte Sinasens. En cas de génération d’une nouvelle clé, l’ancienne est irrémédiablement détruite et ne peut plus être utilisée.

3.5 Codes de retour HTTP

L’API SinaSens ne retourne qu’un nombre limité de codes HTTP :

200 : la requête a été correctement exécutée.
400 : erreur de requête. Un paramètre est manquant ou invalide.
401 : clé d’api manquante ou invalide (login et/ou password).
403 : accès refusé ou requête non autorisée.
404 : la ressource pour la requête demandée n’a pas été trouvée.
429 : trop de requêtes. Fréquence de requêtes trop élevée.
500 : erreur inconnue.

3.6 Nom du fichier en sortie CSV

Le format du nom de sortie du fichier CSV à la suite d’une requête est composé du numéro d’identification du device, du nom de la requête, de la date et de l’heure de la génération du fichier :

<id du device>_<requête>_<année>_<mois>_<jour>_<heures>_<minutes>_<secondes>.csv

Par exemple :

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 Historique d’un device

Requête

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

Paramètres

Paramètre	Commentaires
LOGIN	Requis. Identifiant de la clé d’API (ex: c428g2730739in2i23fk23tk).
PASSWORD	Requis. Mot de passe de la clé d’API (ex: ms7mg0bry06gf7i1hnyf8e9mym6jx58t).
DEVICE	Requis. Numéro de série du transmetteur Sinafis dont on souhaite récupérer l’historique (ex. 36E975).
FROMDATE	Optionnel. Date et heure du début de recherche dans l’historique. Le format est AAAA-MM-JJ HH:MM:SS où AAAA représente l’année, MM le mois, JJ le jour, HH l’heure en format 24h, MM les minutes, SS les secondes. Si le paramètre « fromDate » est omis, la recherche commencera sur le premier événement trouvé dans l’historique.
TODATE	Optionnel. Date et heure de la fin de recherche dans l’historique. Le format est AAAA-MM-JJ HH:MM:SS où AAAA représente l’année, MM le mois, JJ le jour, HH l’heure en format 24h, MM les minutes, SS les secondes. Si le paramètre « toDate » est omis, la recherche finira sur le dernier événement trouvé dans l’historique.
MAX	Optionnel. Nombre maximum d’événements à retourner. Si le paramètre « max » est omis ou si « max=0 », tous les événements trouvés dans la période de recherche seront retournés.
GPS	Optionnel. Option de retour des informations de position GPS du device. 1 -> les positions GPS seront retournées dans l’historique, 0 -> les positions GPS ne seront pas retournées dans l’historique. Si le paramètre « gps » est omis, les positions GPS ne seront pas retournées dans l’historique.
MODE	Optionnel. Format sous lequel les données sont retournées. Il y a 2 formats possibles : JSON ou CSV. Si le paramètre « mode » est omis, le format de sortie est CSV.

Paramètres de sortie de requête (CSV ou JSON)

Paramètre CSV	Paramètre JSON	Commentaires
DATE_UNIX	dateUnix	Date de l’événement exprimée en nombre de secondes depuis le premier janvier 1970 minuit UTC.
DATE	date	Date de l’événement sous la forme jj/mm/aaaa UTC.
HEURE	heure	Heure de l’événement sous la forme hh:mm:ss.
ID	device	Numéro du transmetteur Sinasens.
LATITUDE	latitude	Latitude en degré décimaux (valeur positive pour Nord et négative pour Sud). Null si l’évènement n’est pas lié à une trame GPS.
LONGITUDE	longitude	Longitude en degré décimaux (valeur positive pour Est et négative pour Ouest). Null si l’évènement n’est pas lié à une trame GPS.
TEMP1	temp1	Température de la sonde 1 en degrés Celsius (-120°C à +12°C). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
HUM1	hum1	Humidité de la sonde 1 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
TEMP2	temp2	Température de la sonde 2 en degrés Celsius (-120°C à +12°C). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
HUM2	hum2	Humidité de la sonde 2 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
TEMP3	temp3	Température de la sonde 3 en degrés Celsius (-120°C à +12°C). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée
HUM3	hum3	Humidité de la sonde 3 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée
TEMP4	temp4	Température de la sonde 4 en degrés Celsius (-120°C à +12°C). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
HUM4	hum4	Humidité de la sonde 4 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
TENSION	tension	Tension de la pile au moment de la transmission en volt.
SIGNAL	signal	Qualité du signal radio de la trame transmise (0 à 4) 0=limite, 1=moyen, 2=bon, 3=très bon, 4=excellent

Exemple de requête au format JSON

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

Exemple de réponse au format JSON

[
 {
  "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"
 }
]

Exemple de requête au format CSV

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

Exemple de réponse au format CSV

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

Exemples de demandes d’historique

Les 15 derniers événements du device 36E975 sans le GPS

En CSV :

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

En JSON :

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

Tous les événements du device 36E975 du 1 mai 2019 au 2 mai 2021

En 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

En 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

Les 36 derniers événements du device 36E975 le 12 août 2019 entre 8h04 et 14h22m18s sans le GPS :

En 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'

En 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

Tous les événements du device 36E975 du mois de juin 2019 avec le GPS

En CSV :

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

En 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 Position GPS d’un device

Requête

gps.php

Structure

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

Paramètres

Paramètre	Commentaires
LOGIN	Requis. Identifiant de la clé d’API (ex. c428g2730739in2i23fk23ts).
PASSWORD	Requis. Mot de passe de la clé d’API (ex. ms7mg0bry06gf7i1hnyf8e9mym6jx58a).
DEVICE	Requis. Numéro de série du transmetteur Sinasens dont on souhaite récupérer l’historique (ex. F6F2F).
MAX	Optionnel. Nombre maximum d’événements à retourner. Si le paramètre « max » est omis ou si « max=0 », tous les événements trouvés dans la période de recherche seront retournés.
MODE	Optionnel. Format sous lequel les données sont retournées. Il y a 2 formats possibles : JSON ou CSV. Si le paramètre « mode » est omis, le format de sortie est CSV.

Paramètres de sortie de requête (CSV ou JSON)

Paramètre CSV	Paramètre JSON	Commentaires
DATE_UNIX	dateUnix	Date de l’événement exprimée en nombre de secondes depuis le premier janvier 1970 minuit UTC.
DATE	date	Date de l’événement sous la forme jj/mm/aaaa UTC.
HEURE	heure	Heure de l’événement sous la forme hh:mm:ss.
ID	device	Numéro du transmetteur Sinasens.
LATITUDE	latitude	Latitude en degré décimaux (valeur positive pour Nord et négative pour Sud). Null si l’évènement n’est pas lié à une trame gps.
LONGITUDE	longitude	Longitude en degré décimaux (valeur positive pour Est et négative pour Ouest). Null si l’évènement n’est pas lié à une trame gps.

Exemple de requête au format JSON

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

Exemple de réponse au format JSON

[
 {"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"
 }
]

Exemple de requête au format CSV

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

Exemple de réponse au format CSV

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

Exemples de demandes de position GPS

La dernière position GPS connue du device 36E975

En CSV :

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

En JSON :

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

Les 5 dernières positions GPS connues du device 36E975

En CSV :

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

En JSON :

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

Toutes les positions GPS connues du device 36E975

En CSV :

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

En JSON :

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

doc.pdf

Besoin d'aide ?

Notre équipe vous accompagne et pourra répondre à toutes vos questions.

Prendre contact