API eedomus

Documentation eedomus

Sommaire

Faites en plus avec l'API eedomus

Introduction

L'API eedomus vous offre une panoplie de fonction pour manipuler les données de votre compte eedomus. Vous pouvez consulter les données de vos capteurs mais aussi piloter vos actionneurs.

Avec cet API temps réel, il est possible de développer des applications pour enrichir les possibilités d'eedomus. N'utilisez pas d'URL non listé dans cette page pour vos développements car vous prendriez le risque qu'ils ne soient pas maintenus.

Les conditions générales s'appliquent, l'utilisation de l'API eedomus est libre pour un usage non commercial.

L’ensemble des fonctions de l'API peut être appelé avec des requêtes HTTP GET ou HTTP POST.

Deux API sont disponibles, l'API Cloud sur la plate-forme serveur eedomus et l'API locale sur la box eedomus. Il est conseillé d'utiliser l'API locale dans la mesure du possible, en particulier pour ne pas entrer dans le cadre des limitations de l'API Cloud suivant le niveau de service Free ou Premium.

Pour recevoir vos identifiants de l'API, les révoquer, ou utiliser le constructeur de requête, aller dans secure.eedomus.com : Configuration => Mon compte (le lien API est dans l'onglet Mon compte). Les identifiants sont disponibles pour le compte principal et les comptes secondaires de type complet.

Format des requêtes 

https://api.eedomus.com/[request_type]?action=[service.action]&[parameters]


[request_type] est le type de la requête,

[service.action] est l'action a exécuter pour le service donné,

[parameters] sont des paramètres, obligatoires ou optionnels, à fournir au service donné.

Format des réponses

Les réponses aux requêtes HTTP sont au format JSON 

{
  success: 1
}


Le champ success est obligatoire et vaudra 1 si la requête a fonctionné correctement.

Sinon, il vaudra 0 et des explications complémentaires seront données dans le champ body. 

{
   success: 0,
   body:
   {
     error_code: 1,
     error_msg: "Authentification error."
   }
}

La liste des codes d'erreur (error_code) est disponible ici.

Authentification

Toutes les requêtes doivent être associées à un utilisateur eedomus valide créé sur https://secure.eedomus.com

L'authentification à l'API est différente de celle utilisée sur le portail eedomus. Sur le portail, un utilisateur est authentifié par son identifiant et mot de passe. Avec l'API eedomus l'authentification se fait avec un api_user et un api_secret qui peuvent être demandés et révoqués à tout moment en vous rendant sur la section Mon compte du portail eedomus.

Pour des raisons de sécurité, api_user/api_secret sont envoyés uniquement par mail, pour les récupérer, rendez vous sur https://secure.eedomus.com, et allez dans Configuration / Mon compte / Paramètres et cliquez sur Identifiants pour l'API -> Envoyer

Protocole

L'API eedomus utilise de manière préférentielle le protocole HTTPS (Les données échangées sont chiffrées) mais il est possible d'autoriser l'utilisation d'HTTP dans les options de son compte.

API Local (LAN)

Les fonctions de l'API eedomus sont progressivement disponible sur votre box eedomus (en plus de pouvoir se faire sur les serveurs eedomus).

Pour utiliser ce mode LAN, remplacez simplement api.eedomus.com par IP_OF_YOUR_BOX/api


A ce jour, les fonctions suivantes sont disponibles en mode LAN:


Exemple : (Si l'adresse IP de votre eedomus box est 192.168.0.30): 

http://192.168.0.30/api/get?action=auth.test&api_user=XXXX&api_secret=XXXX

Nota 1: Si l'appel à l'API local est fait depuis la box elle même (Ex. Actionneur HTTP) les paramètres api_user et api_secret peuvent être omis (Il faut alors utiliser des url sous la forme http://localhost/api/).

Nota 2: l'API local ne peut être utilisé en HTTPS contrairement à l'API serveur.

Fonctions de l'API

get -> auth.test

Permet de réaliser un test d'authentification:

Format de la requête 

https://api.eedomus.com/get?action=auth.test&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel format string json ou xml (json par défaut si le paramètre n'est pas précisé)

Exemple de réponse 

{
 "success": 1
}


get -> periph.caract

Renvoie les caractéristiques de base d'un périphérique:

Format de la requête 

https://api.eedomus.com/get?action=periph.caract&periph_id=XXXX&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire periph_id integer Le Code API du périphérique

Vous pouvez spécifier plusieurs périphériques en séparant leur Code API par une virgule (ex. periph_id=1,2,3)

Ou l'ensemble de vos périphériques en précisant periph_id=all

Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel show_config int 0 ou 1 (Affiche des caractéristiques supplémentaires pour le périphérique)
Optionnel format string json ou xml (json par défaut si le paramètre n'est pas précisé)

Exemple de réponse 

{ 
 "success": 1,
 "body": 
 { 
  "name": "Mouvement Atelier",
  "last_value": "100",
  "last_value_text": "Mouvement",
  "battery": "60",
  "last_value_change": "2010-03-29 14:51:22"
 }
}

Description des champs de la réponse

Nom Type Description
name string Nom du périphérique
last_value string Dernière valeur du périphérique
last_value_text string Description de la valeur du périphérique si disponible
battery string Niveau de la batterie en pourcentage
last_value_change string Date/heure correspondant à cette dernière valeur (Au format AAAA-MM-JJ HH:MM:SS)

get -> periph.list

Renvoie la liste de périphériques rattachés à votre compte:

Format de la requête 

https://api.eedomus.com/get?action=periph.list&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel notes int 1 pour ajouter les notes utilisateur dans le résultat
Optionnel format string json ou xml (json par défaut si le paramètre n'est pas précisé)

Exemple de réponse 

{
   "success": 1,
   "body": [
       {
           "periph_id": "756",
           "parent_periph_id": "",
           "name": "Journée en cours",
           "value_type": "list",
           "room_id": "1",
           "room_name": "Programmation",
           "usage_id": "18",
           "channel_id": "",
           "usage_name": "Etat technique: Journée",
           "creation_date": "2013-04-30 14:11:37",
           "battery": ""
       },
       {
           "periph_id": "757",
           "parent_periph_id": "",
           "name": "Phase de la journée",
           "value_type": "list",
           "room_id": "1",
           "room_name": "Programmation",
           "usage_id": "34",
           "channel_id": "",
           "usage_name": "Etat technique: Phase",
           "creation_date": "2013-04-30 14:11:37",
           "battery": ""
       },
       { ... }
   ]
}

Description des champs de la réponse

Nom Type Description
periph_id integer Code API du périphérique
parent_periph_id string Code API du périphérique principal (S'il s'agit d'un périphérique à plusieurs canaux)
name string Nom du périphérique
value_type string Type de valeur (float, string, list)
room_id integer Code API de la pièce du périphérique
room_name string Nom de la pièce du périphérique
usage_id integer Code API de l'usage du périphérique
usage_name string Nom de l'usage du périphérique
channel_id integer Canal du périphérique (s'il s'agit d'un périphérique à plusieurs canaux)
creation_date string Date de création du périphérique
battery string Niveau de la batterie en pourcentage

get -> periph.history

Retourne l'historique des valeurs d'un périphérique:

Format de la requête 

https://api.eedomus.com/get?action=periph.history&periph_id=XXXX&start_date=YYYY-MM-DD HH:MM:SS&end_date=YYYY-MM-DD HH:MM:SS&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire periph_id integer Le Code API du périphérique
Optionnel start_date date Renvoie des données après la date/heure spécifié (Au format AAAA-MM-JJ HH:MM:SS)
Optionnel end_date date Renvoie des données avant la date/heure spécifié (Au format AAAA-MM-JJ HH:MM:SS)
Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel format string json, xml, csv, table (HTML) (json par défaut si le paramètre n'est pas précisé)
Optionnel show_all string 1 si vous souhaitez voir même les valeurs répétées


|}

Exemple de réponse 

{
 "success": 1,
 "body":
 {
   "history": 
   [
    ["69","2010-02-12 14:35:50"],
    ["69","2010-02-12 14:35:50"],
    ["87","2010-04-03 19:36:38"],
    ["82","2010-04-03 20:06:47"],
    ["87","2010-04-03 21:07:03"],
    ["81","2010-04-03 23:17:36"],
    ["87","2010-04-03 23:47:43"],
    ["76","2010-04-04 01:18:13"],
    ["81","2010-04-04 01:38:18"],
    ["87","2010-04-04 03:40:10"],
    ["93","2010-04-04 06:40:59"]
   ]
 }
}

Description des champs de la réponse

Nom Type Description
history array Un tableau de [value, date]. value est une chaine de caractères, date est au format AAAA-MM-JJ HH:MM:SS

Nota

La réponse est limitée au 10 000 1ère valeurs, dans ce cas le champ suivant est ajouté dans le JSON de réponse: 

history_overflow: 10000,

get -> periph.value_list

Liste les valeurs possible d'un périphérique. (Uniquement disponible pour les périphériques de type Liste)

Format de la requête 

https://api.eedomus.com/get?action=periph.value_list&periph_id=XXXX&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire periph_id integer Le Code API du périphérique

Vous pouvez spécifier plusieurs périphériques en séparant leur Code API par une virgule (ex. periph_id=1,2,3)

Ou l'ensemble de vos périphériques en précisant periph_id=all

Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel format string json ou xml (json par défaut si le paramètre n'est pas précisé)

Exemple de réponse 

{
   "success": 1,
   "body": {
       "periph_id": 72762,
       "values": [
           {
               "value": "0",
               "description": "Off",
               "icon": "lamp_off.png"
           },
           {
               "value": "100",
               "description": "On",
               "icon": "lamp_on.png"
           }
       ]
   }
}


set -> periph.value

Définie une valeur sur un périphérique. Le périphérique peut être un capteur (dans ce cas la valeur est stockée dans son historique) ou un actionneur (le périphérique reçoit un ordre de changement de valeur)

Format de la requête 

https://api.eedomus.com/set?action=periph.value&periph_id=XXXX&value=XXXX&value_date=YYYY-MM-DD HH:MM:SS&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire periph_id integer Le Code API du périphérique
Obligatoire value string La valeur a définir (La liste est visible dans l'onglet Valeur du périphérique).

Vous pouvez également utiliser la syntaxe "toggle" qui permet de basculer d'une valeur à l'autre. Ex. pour une lampe à variateur: value=TOGGLE[0|30|100], après que la valeur soit passée à 100, le prochain appel de l'API passera la valeur à 0 (On boucle sur la liste des valeurs).

Attention: les caractères spéciaux doivent être encodés pour les URL (Ex. "€" doit être remplacé par "%80")

Optionnel value_date date En général non nécessaire. Spécifie une date/heure précise pour la valeur. Au format AAAA-MM-JJ HH:MM:SS. Si ce paramètre n'est pas spécifié, la date correspondante sera celle de l'appel à l'API.
Optionnel mode string Choisir "mobile" pour avoir un résultat affichable sur son Smartphone et l'ajouter à son dashboard/écran d'accueil.
Optionnel update_only int 1 si vous souhaitez mettre à jour la valeur du périphérique eedomus sans demander d'action physique sur le matériel correspondant
Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel format string json ou xml (json par défaut si le paramètre n'est pas précisé)
Optionnel battery int 0-100 (pourcentage de la batterie) ou 255 (batterie faible)

Exemple de réponse 

{
 "success": 1,
 "body":
 {
   "result": "[OK]"
 }
}

Nota: Un succés signifie que l'ordre a bien été pris en compte au niveau API et qu'il sera transmis au périphérique dès que possible. Cela ne signifie pas que le périphérique est joignable (particulièrement pour les périphériques sans fil) et qu'il a été actionné (le périphérique peut être débranché).

Description des champs de la réponse

Nom Type Description
result string Message texte renvoyé par le serveur

set -> periph.macro

Active une macro sur un périphérique.

Format de la requête 

https://api.eedomus.com/set?action=periph.macro&macro=XXXX&api_user=XXXX&api_secret=XXXX

Description des paramètres de la requête

Obligatoire Nom Type Description
Obligatoire macro integer Identifiant de la macro
Obligatoire api_user string "Identifiant" API
Obligatoire api_secret string "Mot de passe" API
Optionnel format string json ou xml (json par défaut si le paramètre n'est pas précisé)
Optionnel dynamic_value integer Valeur du paramètre dynamique de macro (ex. durée avant l'extinction)

Exemple de réponse 

{
 "success": 1,
 "body":
 {
   "result": "[OK]"
 }
}

Nota: Un succés signifie que l'ordre a bien été pris en compte au niveau API et qu'il sera transmis au périphérique dès que possible. Cela ne signifie pas que le périphérique est joignable (particulièrement pour les périphériques sans fil) et qu'il a été actionné (le périphérique peut être débranché).

Description des champs de la réponse

Nom Type Description
result string Message texte renvoyé par le serveur


Codes d'erreur

Code d'erreur Description
1 Authentification invalide
2 Paramètre manquant XXXX
3 Le périphérique n'existe pas.
4 Action invalide XXXX
5 Erreur dans le format du paramètre XXXX
6 Valeur inexistante pour ce périphérique XXXX
7 Erreur serveur XXXX
8 Erreur de bascule (Toggle) XXXX

Génération automatique des requêtes API

Le constructeur automatique de requête API est disponible sur secure.eedomus.com depuis 2 endroits.

En allant sur la page de configuration d'un périphérique dans la section Paramètres expert, vous accédez à un générateur automatique de requête en cliquant sur l’icône en forme de clé située devant le code API.

Ensuite, vous sélectionnez dans les listes déroulantes le type d'action et le périphérique concerné. Le construction de requêtes API est ainsi grandement facilitée.

Le générateur automatique est également accessible depuis MonCompte/Configuration/Consultez vos identifiants API (voir image ci-dessous).

Statistiques d'usage de l'API

Si vous recevez un message d'alerte de dépassement de quota API, vous pouvez consulter les statistiques d'usage.

L'accès s'effectue par la page Mon Compte (Consultez vos identifiants). Vous cliquez ensuite sur statistiques d'usage. Vous avez accès à des statistiques par type d'appels.

Exemples

Vous pouvez télécharger et modifier librement ces exemples d'utilisation de l'API pour démarrer vos propres projets:

C

eedomus_api_c.zip

C#

Télécharger gratuitement Visual C# Express

eedomus_api_csharp.zip

PHP

eedomus_api_php.zip