Eedomus API

From eedomus - Documentation

Jump to: navigation, search

Contents

Extend your possibilities with eedomus API

Introduction

The eedomus API provides online functions to access your eedomus system. You can view the data of your sensors and even act on actuators.

With this simple yet powerfull realtime API, third parties can develop applications to enhance the usage of our smart home platform. Please, do not use any other URL than those listed on this page as they are subject to change without notice.

The Terms of Use applies. The API is licensed free for non commercial purpose.

All API functions can be requested on the web using HTTP GET or POST requests.


Request format 

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

Where :

[request_type] get or set datas on the following service,

[service.action] is the action you want to perform on the requested service,

[parameters] are parameters, mandatory or optional, passed to the requested service.

Response format

Responses to HTTP request are in JSON format 

{
  success: 1
}


The success field is mandatory and will return a 1 in case your request succeed.

Otherwise it will return 0 and gives you explanations in the body field status. 

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

The error_code list is available here.

Authentification

All requests must be associated to a valid eedomus user created on https://secure.eedomus.com

The authentification for the API is different from the portal authentification. On the portal a user is authentified using its login and password. On eedomus API the authentification must be done with an api_user and an api_secret which can be requested and revoked on your account configuration page.

For security reasons, api_user/api_secret will only be sent to you by email, to request yours on https://secure.eedomus.com, go on Configuration / My Account / Parameters and click Send API identifiers

Protocol

The eedomus API uses preferentially HTTPS. Data and request details are encrypted. It is possible to authorize the HTTP in the account options (disabled by default).

Local API (LAN)

API Functions are progressively available on your eedomus box.

To use them, just replace api.eedomus.com with IP_OF_YOUR_BOX/api

Actually, the following functions are available:

Example (Assuming 192.168.0.30 is the IP of your eedomus box): 

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

API Functions

get -> auth.test

Test authentification parameters:

Request format 

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

Request parameters description

Mandatory Name Type Description
Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional format string json or xml (Default to json when ommited)

Response Example 

{
 "success": 1
}


get -> periph.caract

Get basic caracteristics from a user peripheral:

Request format 

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

Request parameters description

Mandatory Name Type Description
Mandatory periph_id integer The peripheral identifier (How to get your peripherals identifiers)

You can specify multiple peripherals by separating their identifier with a comma (ex. periph_id=1,2,3)

Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional format string json or xml (Default to json when ommited)

|}

Response Example 

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

Response fields description

Name Type Description
name string The peripheral name
last_value string The peripheral last value
last_value_change string The peripheral last value. Format is YYYY-MM-DD HH:MM:SS

get -> periph.list

Get periph list attached to your user account:

Request format 

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

Request parameters description

Mandatory Name Type Description
Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional notes int 1 to add user notes on the result
Optional format string json or xml (Default to json when ommited)

|}

Response Example 

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


Response fields description

Name Type Description
periph_id integer API code of the devie
parent_periph_id string API code of the parent device (if multi channel device)
name string Name of the device
room_id integer API code of the device room
room_name string Name of the device room
usage_id integer API code of the device usage
usage_name string Name of the device usage
creation_date string Creation date of the device

get -> periph.history

Get values history from a user peripheral:

Request format 

http://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

Request parameters description

Mandatory Name Type Description
Mandatory periph_id integer The peripheral identifier (How to get your peripherals identifiers)
Optional start_date date Return data only after or equal specified datetime. Format is YYYY-MM-DD HH:MM:SS
Optional end_date date Return data only before or equal specified datetime. Format is YYYY-MM-DD HH:MM:SS
Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional format string json or xml (Default to json when ommited)


|}

Response Example 

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

Response fields description

Name Type Description
history array An array of [value, date]. value is a string, date format is YYYY-MM-DD HH:MM:SS

Nota

Response is limited to first 10K values, in this case the following is added to the json output: 

history_overflow: 10000,

get -> periph.value_list

List the possible values of a device (only for device with a list' type)

Request format 

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

Request description

Mandatory Nom Type Description
Mandatory periph_id integer API code of device

You mail specify several devices with a coma between the API Code (ex. periph_id=1,2,3)

Or all of the devices whith periph_id=all

Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional format string json or xml (json by default when ommited)

Response example 

{
   "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

Set a value for a user peripheral. The peripheral could be a sensor (the value is stored in his history) or a actuator (the peripheral is asked to change for the new value)

Request format 

http://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

Request parameters description

Mandatory Name Type Description
Mandatory periph_id integer The peripheral identifier (How to get your peripherals identifiers)
Mandatory value string The value to store (How to get your peripherals values).

You can also use the "toggle" syntax to switch between values. Ex. for a dimmer light: value=TOGGLE[0|30|100], after 100 is set, next api call will set the light to 0.

Optional value_date date Usually ommited. Specify a datetime for the value. Format is YYYY-MM-DD HH:MM:SS. When ommited, the datetime affected to the value will be "now" according to the eedomus server time.
Optional mode string Set to "mobile" to have a smartphone friendly action that you can add to your phone dashboard.
Optional update_only int Set to 1 to update the value without lauching the action
Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional format string json or xml (Default to json when ommited)

|}

Response Example 

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

Nota: A success means that the order has been successfully registered at the API level and will be transmetted to the module. It does not mean that the module is reachable (especially for radio module) and has effectively changed to this value.

Response fields description

Name Type Description
result string A text message from the server

set -> periph.macro

Activate a macro on a user peripheral.

Request format 

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

Request parameters description

Mandatory Name Type Description
Mandatory macro integer The macro identifier
Mandatory api_user string User's API login
Mandatory api_secret string User's API secret
Optional format string json or xml (Default to json when ommited)


|}

Response Example 

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

Nota: A success means that the order has been successfully registered at the API level and will be transmetted to the module. It does not mean that the module is reachable (especially for radio module) and has effectively changed to this value.

Response fields description

Name Type Description
result string A text message from the server


Error codes

Error code Description
1 Invalid authentification
2 Missing parameter XXXX
3 Peripheral does not exists.
4 Invalid action XXXX
5 Parameter format error XXXX
6 Unknown peripheral value XXXX
7 Server error XXXX
8 Toggle error XXXX

Automatic generation of API requests

By going to Configuration / My account / , and clicking on eedomus API, you access a personnalized automatic request generator (see on the right).

Simply select from the dropdown lists the type of action and specific device. The API query building is thus greatly facilitated.


Examples

Here are a few examples using eedomus API that you can use to start your own project:

C

eedomus_api_c.zip

C#

Download Visual C# Express for free

eedomus_api_csharp.zip

PHP

eedomus_api_php.zip