Domoticz API/JSON URL's

From Domoticz
Jump to: navigation, search

Domoticz has the ability to interact with all switches and sensors using JSON. This page will describe how to use this API.

Contents

Format

http://<username:password@>domoticz-ip<:port>/json.htm?api-call
  • <username:password@> = the username and password to access Domoticz, this is optional.
  • domoticz-ip = the IP-address or hostname of your Domoticz installation.
  • <:port> = the port number of your Domoticz installation, this is optional.
eg. http://192.168.1.2:8080/json.htm?type=command&param=udevice&idx=$idx&nvalue=0&svalue=79

Hint: You can have a look at the database for the nValue/sValue, or the .cpp code.

Making output more readable

By default, your browser will display the JSON-output in a unordered mess. To make it more readable you could use a browser plugin that formats the JSON to a more human-readable layout.
For Google Chrome you could use JSONView (Chrome web store). For other browsers a similar extension will probably exist. Look in the extensions/add-on store of your browser.

Authorization

When using some method other than a browser to connect to Domoticz it may be necessary to do Authorization differently. Authorization over HTTP is done by setting the "Authorization" HTTP request header when sending the request to Domoticz. The value of this header is a base64 encoded string of the username and password. When connecting to Domoticz using a browser and the URL method above the browser sets the appropriate header. When creating your own app or script this is not always done for you.

  • First the username and password are combined into one string "username:password"
  • This string is encoded using the RFC2045-MIME version of base64
  • The authorization method and a space i.e. "Basic " is then put before the encoded string.

This results in a header in the following format:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

How the header is send differs per programming language. Check the documentation of the language of your choice on how to set http request headers.

This method works with both the Basic-Auth and Login page options.

Response

All responses include a status which is either OK on success or ERR on failure

{
   "status" : "OK"
}

General usage

Retrieve status of specific device

You can get the status of a specific device with:

/json.htm?type=devices&rid=IDX
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")

Get all devices of a certain type

/json.htm?type=devices&filter=all&used=true&order=Name

This will return information about all the devices. If you want to retrieve information for a certain devicetype, you can use the following filters:

light = Get all lights/switches
weather = Get all weather devices
temp = Get all temperature devices
utility = Get all utility devices

Get sunrise and sunset times

/json.htm?type=command&param=getSunRiseSet
{
   "ServerTime" : "Sep 30 2013 17:15:21",
   "Sunrise" : "07:38:00",
   "Sunset" : "19:16:00",
   "status" : "OK",
   "title" : "getSunRiseSet"
}

Add a log message to the Domoticz log

You can add a log message to the system with:

/json.htm?type=command&param=addlogmessage&message=MESSAGE
  • MESSAGE = a string you want to log

Lights and switches

Get all lights/switches

/json.htm?type=command&param=getlightswitches

OR

 /json.htm?type=devices&filter=light&used=true&order=Name

Example output:


{
   "result" : [
      {
         "IsDimmer" : false,
         "Name" : "Bedroom lights",
         "SubType" : "Energenie",
         "Type" : "Lighting 1",
         "idx" : "43"
      },
      {
         "IsDimmer" : false,
         "Name" : "Hall",
         "SubType" : "Energenie",
         "Type" : "Lighting 1",
         "idx" : "30"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge Light Front",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "32"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge Lights All",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "66"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge light back",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "33"
      }
   ],
   "status" : "OK",
   "title" : "GetLightSwitches"
}

Turn a light/switch on

/json.htm?type=command&param=switchlight&idx=99&switchcmd=On

Turn a light/switch off

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Off
  • idx = id of your device (in this example 99).
  • switchcmd = "On" or "Off" (case sensitive!)


{
   "status" : "OK",
   "title" : "SwitchLight"
}

Set a dimmable light to a certain level

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Set%20Level&level=6
  • Level should be a value between 1 (0%) and 16 (100%). Though in some cases you need to use the percentage, so if 1 to 16 doesn't work for you , then try 1 to 100 (without the percentage symbol)
  • When the light is off, it will be turned on
{
   "status" : "OK",
   "title" : "SwitchLight"
}

Toggle a switch state between on/off

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Toggle
{
   "status" : "OK",
   "title" : "SwitchLight"
}

Scenes / Groups

Get all the scenes & groups

/json.htm?type=scenes

Example output:

{
   "result" : [
      {
         "Favorite" : 1,
         "HardwareID" : 0,
         "LastUpdate" : "2013-09-29 19:11:01",
         "Name" : "My Scene",
         "Status" : "Off",
         "Timers" : "true",
         "Type" : "Scene",
         "idx" : "9"
      },
      {
         "Favorite" : 1,
         "HardwareID" : 0,
         "LastUpdate" : "2013-09-30 11:49:13",
         "Name" : "My Group",
         "Status" : "Off",
         "Timers" : "false",
         "Type" : "Group",
         "idx" : "3"
      }
   ],
   "status" : "OK",
   "title" : "Scenes"
}

Turn a scene / group on or off

/json.htm?type=command&param=switchscene&idx=&switchcmd=
  • idx = id of your scene/group.
  • switchcmd = "On" or "Off" (case sensitive!)
  • Scenes can only be turned On
{
   "status" : "OK",
   "title" : "SwitchScene"
}

Add a scene (0)

/json.htm?type=addscene&name=scenename&scenetype=0

Add a group (1)

/json.htm?type=addscene&name=scenename&scenetype=1

Delete a scene or group

/json.htm?type=deletescene&idx=number

List devices in a scene

/json.htm?type=command&param=getscenedevices&idx=number&isscene=true

Add device to a scene

/json.htm?type=command&param=addscenedevice&idx=number&isscene=true&devidx=deviceindex&command=1&level=number&hue=number

Delete device from a scene

/json.htm?type=command&param=deletescenedevice&idx=number

List timers of a scene

/json.htm?type=scenetimers&idx=number

Example output:

{
   "result" : [
      {
         "Active" : "true",
         "Cmd" : 0,
         "Date" : "07-02-2016",
         "Days" : 128,
         "Hue" : 0,
         "Level" : 100,
         "Randomness" : true,
         "Time" : "00:01",
         "Type" : 5,
         "idx" : "16"
      }
   ],
   "status" : "OK",
   "title" : "SceneTimers"
}

Add timer to a scene

/json.htm?type=command&param=addscenetimer&idx=number&active=&timertype=&date=&hour=&min=&randomness=&command=&level=&days=
  • idx = index of your scene/group.
  • active = true/false
  • timertype = 0 = Before Sunrise, 1 = After Sunrise, 2 = On Time, 3 = Before Sunset, 4 = After Sunset, 5 = Fixed Date/Time
  • date = MM-DD-YYYY
  • hour = hour
  • min = minute
  • randomness = true/false
  • command = On/Off
  • level = 0..100 (%)
  • days = 0x80 = Everyday, 0x100 = Weekdays, 0x200 = Weekends, 0x01 = Mon, 0x02 = Tue, 0x04 = Wed, 0x08 = Thu, 0x10 = Fri, 0x20 = Sat, 0x40 = Sun

Server control

Shutdown system

/json.htm?type=command&param=system_shutdown
{
   "status" : "OK",
   "title" : "SystemShutdown"
}

Reboot system

/json.htm?type=command&param=system_reboot
{
   "status" : "OK",
   "title" : "SystemReboot"
}

Create commands

Create virtual hardware

/json.htm?type=command&param=addhardware&htype=15&port=1&name=Sensors1&enabled=true

afterward to get the id, either you have your last created id from an index you maintain or sort the hardware page for last ID:

 /json.htm?type=hardware

Create a virtual sensor

Temp+Humidity (see below for values)

/json.htm?type=createvirtualsensor&idx=29&sensortype=82

Electricity (see below for values)

/json.htm?type=createvirtualsensor&idx=29&sensortype=90

and then get the device id from the list:

/json.htm?type=devices&filter=all&used=true&order=Name
1 Pressure (Bar) 0.0 	      	     nvalue=BAR (TBC)        
2 Percentage     0.0 	      	     nvalue=PCT (TBC)	        
80 TEMP          0.0     	     svalue=TEMP
81 HUM           1		     nvalue=HUM svalue=1 to 3
82 TEMP_HUM      0.0;50;1 	     svalue=TEMP;HUM;HUM_STATUS
84 TEMP_HUM_BARO 0.0;50;1;1010;1    svalue=TEMP;HUM;HUM_STATUS;BARO;BARO_FCST
85 RAIN          0;0		     svalue=RAIN;Rain in mm/h
86 WIND          0;N;0;0;0;0  	     svalue=WIN_SPD;WIND_DIR;?;?;?;?
87 UV            0;0		     svalue= (TBC)
113 RFXMeter     0		     Can have several values, another order has to be sent to set the sub type:	   
							type 3	Counter:   svalue=COUNTER
							type 2	Water:	   svalue=VOLUME
							type 1	Gas:
							type 0	Energy:
90 ENERGY        0;0.0		     svalue=POWER;ENERGY
249 TypeAirQuality    0	     nvalue=PPM

For the RFXMeter, another request is needed to set the utility, url is:

/json.htm?type=setused&idx=DEVICE_ID&name=RFXMeter&switchtype=SUBTYPE_VALUE&used=true

where DEVICE_ID is the device name, and the SUBTYPE_VALUE is one of:

0 for Energy
1 for Gas
2 for Water
3 for Counter

Update devices/sensors

Expert usage. Directly set device parameters via JSON.
Be very carefully when firing values to domoticz.db. There is a chance to crash the database if parameters are wrong or missing.
Especially Domoticz release <=Beta 1.1634 or stable <=1.1396 are more sensitive. Later releases will have more protection.

First go to the devices tab and notice the device index (idx) of the device you want to change

Temperature

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature


Humidity

/json.htm?type=command&param=udevice&idx=IDX&nvalue=HUM&svalue=HUM_STAT

The above sets the parameters for a Humidity device

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • HUM = Humidity: 45%
  • HUM_STAT = Humidity_status


Humidity_status can be one of:

  • 0=Normal
  • 1=Comfortable
  • 2=Dry
  • 3=Wet


Barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=BAR;BAR_FOR

The above sets the parameters for a Barometer device from hardware type 'General'

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • BAR = Barometric pressure
  • BAR_FOR = Barometer forecast


Barometer forecast can be one of:

  • 0 = Stable
  • 1 = Sunny
  • 2 = Cloudy
  • 3 = Unstable
  • 4 = Thunderstorm
  • 5 = Unknown
  • 6 = Cloudy/Rain


Temperature/humidity

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;HUM;HUM_STAT
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature
  • HUM = Humidity
  • HUM_STAT = Humidity status


HUM_STAT can be one of:

  • 0=Normal
  • 1=Comfortable
  • 2=Dry
  • 3=Wet


Temperature/humidity/barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;HUM;HUM_STAT;BAR;BAR_FOR

The above sets the parameters for a Temp+Humidity+Barometer device

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature
  • HUM = Humidity
  • HUM_STAT = Humidity status
  • BAR = Barometric pressure
  • BAR_FOR = Barometer forecast


Barometer forecast can be one of:

  • 0 = No info
  • 1 = Sunny
  • 2 = Partly cloudy
  • 3 = Cloudy
  • 4 = Rain


Rain

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=RAINRATE;RAINCOUNTER
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • RAINRATE = amount of rain in last hour
  • RAINCOUNTER = continues counter of fallen Rain in mm

Wind

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=WB;WD;WS;WG;22;24
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • WB = Wind bearing (0-359)
  • WD = Wind direction (S, SW, NNW, etc.)
  • WS = 10 * Wind speed [m/s]
  • WG = 10 * Gust [m/s]
  • 22 = Temperature
  • 24 = Temperature Windchill

UV

 /json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=COUNTER;0
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • COUNTER = Float (in example: 2.1) with current UV reading.

Don't loose the ";0" at the end - without it database may corrupt.

Counter

/json.htm?type=command&param=udevice&idx=IDX&svalue=COUNTER
  • IDX = id of your device (this number can be found in the devices tab in the column "IDX")
  • COUNTER = Integer of the overall total volume.

When there is a counter created, there is a possibility to change the units by clicking on "Change" at the utility tab.

  • Energy (kWh)
  • Gas (m3)
  • Water (m3)
  • Counter (no unit)

The counter will be treated with the divider which is defined in the parameters in the application settings. For example if the counter is set to "Water" and the value is passed as liters, the divider must set to 1000 (as the unit is m3). The device displays 2 values:

  • The status is the overall total volume (or counter).
  • The volume (or counter) of the day (in the top right corner).

The today's volume (or counter) is calculated from the total volume (or counter).

Electricity (instant and counter)

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=POWER;ENERGY
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • POWER = current power
  • ENERGY = cumulative energy in Watt-hours (Wh) (this is just a "dummy" counter, all counting must be done by client)


Electricity P1 smart meter

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • USAGE1= energy usage meter tariff 1
  • USAGE2= energy usage meter tariff 2
  • RETURN1= energy return meter tariff 1
  • RETURN2= energy return meter tariff 2
  • CONS= actual usage power (Watt)
  • PROD= actual return power (Watt)

USAGE and RETURN are counters (they should only count up).
For USAGE and RETURN supply the data in total Wh with no decimal point.
(So if your meter displays f.i. USAGE1= 523,66 KWh you need to send 523660)

Air quality

/json.htm?type=command&param=udevice&idx=IDX&nvalue=PPM
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • PPM = CO2-concentration

Pressure

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=BAR
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • BAR = Pressure in Bar

Create sensor under Hardware > Dummy > Create virtual sensor

Percentage

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=PERCENTAGE
  • IDX = id of your device (this number can be found in the devices tab in the column "IDX")
  • PERCENTAGE = Percentage

Gas

/json.htm?type=command&param=udevice&idx=IDX&svalue=0&svalue=USAGE
  • USAGE= Gas usage in liter (1000 liter = 1 m³)

So if your gas meter shows f.i. 145,332 m³ you should send 145332.
The USAGE is the total usage in liters from start, not f.i. the daily usage.

Lux

/json.htm?type=command&param=udevice&idx=IDX&svalue=VALUE
  • IDX = device ID of Lux device
  • VALUE = value of luminosity in Lux

Voltage

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VOLTAGE
  • IDX = device ID of Voltage device
  • VALUE = value of voltage sensor in Volts

Create sensor under Hardware > Dummy > Create virtual sensor

Text sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEXT
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEXT = Text you want to display

Alert sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=LEVEL&svalue=TEXT
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • Level = (0=gray, 1=green, 2=yellow, 3=orange, 4=red)
  • TEXT = Text you want to display

Distance sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=DISTANCE
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • DISTANCE = distance in cm or inches, can be in decimals. For example 12.6

Selector Switch

/json.htm?type=command&param=switchlight&idx=IDX&switchcmd=Set%20Level&level=LEVEL
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • LEVEL = level of your selector (This number can be found in the edit selectors page, in the column "Level", 0 = Off)

Custom Sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VALUE
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • VALUE = Value (like 12.345)


Additional parameters (signal level & battery level)

There are two additional parameters for the above commands, to specify the signal level (default 12) and the battery level (default 255)

battery level 255 = no battery device, else 0-100
example: &rssi=10&battery=89

User variables

Store a new variable

json.htm?type=command&param=saveuservariable&vname=uservariablename&vtype=uservariabletype&vvalue=uservariablevalue

Where type is 0 to 4:

0 = Integer, e.g. -1, 1, 0, 2, 10 
1 = Float, e.g. -1.1, 1.2, 3.1
2 = String
3 = Date in format DD/MM/YYYY
4 = Time in 24 hr format HH:MM

All formats are checked by the api, when the variable does not match the required format it is not stored.

Update an existing variable

/json.htm?type=command&param=updateuservariable&idx=idx&vname=uservariablename&vtype=uservariabletype
&vvalue=uservariablevalue

List all variables

/json.htm?type=command&param=getuservariables

List one variable:

/json.htm?type=command&param=getuservariable&idx=IDX
  • IDX = id of your variable (This number can be found using the "List all variables" call above)

Delete a variable

/json.htm?type=command&param=deleteuservariable&idx=IDX
  • IDX = id of your variable (This number can be found using the "List all variables" call above)


Room Plans

List all rooms

/json.htm?type=plans&order=name&used=true

List all devices in a room

/json.htm?type=command&param=getplandevices&idx=IDX
  • IDX = id of your room

History

Switch

/json.htm?type=lightlog&idx=IDX

Temperature

/json.htm?type=graph&sensor=temp&idx=IDX&range=day
/json.htm?type=graph&sensor=temp&idx=IDX&range=month
/json.htm?type=graph&sensor=temp&idx=IDX&range=year

Setpoint

See Temperature

Not yet documented

Get all schedules (timers)

../json.htm?type=schedules

Typical result :

{
   "result" : [
      {
         "Active" : "true",
         "Date" : "",
         "Days" : 128,
         "DevName" : "Porch Light",
         "DeviceRowID" : 52,
         "Hue" : 0,
         "IsThermostat" : "false",
         "Level" : 100,
         "MDay" : 0,
         "Month" : 0,
         "Occurence" : 0,
         "Randomness" : "false",
         "ScheduleDate" : "2016-04-01 20:33:00",
         "Time" : "00:20",
         "TimerCmd" : 0,
         "TimerID" : 9,
         "TimerType" : 4,
         "TimerTypeStr" : "After Sunset",
         "Type" : "Device"
      },

Get all schedules(timers) for Devices

../json.htm?type=schedules&filter=device

Get all schedules(timers) for Scenes

../json.htm?type=schedules&filter=scene

Get all schedules(timers) for Thermostats

../json.htm?type=schedules&filter=thermostat