Sinasens

Dernière modification le

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ètreCommentaires
LOGINRequis.
Identifiant de la clé d’API (ex: c428g2730739in2i23fk23tk).
PASSWORDRequis.
Mot de passe de la clé d’API (ex: ms7mg0bry06gf7i1hnyf8e9mym6jx58t).
DEVICERequis.
Numéro de série du transmetteur Sinafis dont on souhaite récupérer l’historique (ex. 36E975).
FROMDATEOptionnel.
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.
TODATEOptionnel.
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.
MAXOptionnel.
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.
GPSOptionnel.
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.
MODEOptionnel.
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 CSVParamètre JSONCommentaires
DATE_UNIXdateUnixDate de l’événement exprimée en nombre de secondes depuis le premier janvier 1970 minuit
UTC.
DATE dateDate de l’événement sous la forme jj/mm/aaaa UTC.
HEURE
heureHeure de l’événement sous la forme hh:mm:ss.
IDdeviceNuméro du transmetteur Sinasens.
LATITUDElatitudeLatitude 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.
LONGITUDElongitudeLongitude 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.
TEMP1temp1Tempé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.
HUM1hum1Humidité de la sonde 1 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
TEMP2temp2Tempé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.
HUM2hum2Humidité de la sonde 2 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
TEMP3temp3Tempé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
HUM3hum3Humidité de la sonde 3 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée
TEMP4temp4Tempé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.
HUM4hum4Humidité de la sonde 4 en % (0 à 100%). Null si la sonde n’existe pas ou si aucune valeur n’est mesurée.
TENSIONtensionTension de la pile au moment de la transmission en volt.
SIGNALsignalQualité 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ètreCommentaires
LOGINRequis.
Identifiant de la clé d’API (ex. c428g2730739in2i23fk23ts).
PASSWORDRequis.
Mot de passe de la clé d’API (ex. ms7mg0bry06gf7i1hnyf8e9mym6jx58a).
DEVICERequis.
Numéro de série du transmetteur Sinasens dont on souhaite récupérer l’historique (ex. F6F2F).
MAXOptionnel.
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.
MODEOptionnel.
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 CSVParamètre JSONCommentaires
DATE_UNIXdateUnixDate de l’événement exprimée en nombre de secondes depuis le premier janvier 1970 minuit
UTC.
DATEdateDate de l’événement sous la forme jj/mm/aaaa UTC.
HEUREheureHeure de l’événement sous la forme hh:mm:ss.
IDdeviceNuméro du transmetteur Sinasens.
LATITUDElatitudeLatitude 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.
LONGITUDElongitudeLongitude 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
Besoin d'aide ?
Notre équipe vous accompagne et pourra répondre à toutes vos questions.
Prendre contact