Using the Philips Hue API

Using the Philips Hue API

Heres how to get started making API calls to your local Philips Hue Bridge

The examples used in this are BASH script examples, but of course you can use any language capable of making a REST-API call.

How to create a user and API key in your local Hue bridge
You will need to press the physical button on your Hue Bridge, then run the script within a few seconds. The returned data will contain the newly created username and API key.
#!/bin/bash
hueIp='IpOfYourHueBridgeHere'
hueUserToCreate='UserNameToBeCreatedHere'
createHueUser=`curl -s -X POST -d "{\"devicetype\":\"$hueUserToCreate\"}" http://$hueIp/api`
echo "createHueUser: $createHueUser"


Get a list of the lights configured in your Hue Bridge
For some nice output, you can use the following BASH script (requires jq be installed):
#!/bin/bash
hueIp='IpOfYourHueBridgeHere'
hueApiKey='HueApiKeyHere'
getLights=`curl -X GET curl -s -X GET $hueIp/api/"$hueApiKey"/lights | jq .`
lightCnt=`echo $getLights | jq '. | length'`
lightLoop='0'
while [ $lightLoop -lt $lightCnt ]
do
lightId=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\($key)"'`
lightOn=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .state.on)"'`
lightType=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .type)"'`
lightName=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .name)"'`
lightModelId=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .modelid)"'`
lightMfgName=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .manufacturername)"'`
lightProductName=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .productname)"'`
lightUniqueId=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .uniqueid)"'`
lightProductId=`echo $getLights | jq -r '. | keys['$lightLoop'] as $key | "\(.[$key] | .productid)"'`
echo ""
echo "LightId: $lightId"
echo "Name: $lightName"
echo "LightOn? $lightOn"
echo "Type: $lightType"
echo "ProductName: $lightProductName"
echo "MfgName: $lightMfgName"
echo "ModelId: $lightModelId"
echo "UniqueId: $lightUniqueId"
echo "ProductId: $lightProductId"
let lightLoop=lightLoop+1
done


Turn a specific light on or off
#!/bin/bash
hueIp='IpOfYourHueBridgeHere'
hueApiKey='HueApiKeyHere'
lightId='7'
lightOn="true"
lightPut=`curl --request PUT --data "{\"on\":$lightOn}" http://$hueIp/api/$hueApiKey/lights/"$lightId"/state/`
echo "lightPut:"; echo "$lightPut"


Change the brightness of a specific light over a period of time
#!/bin/bash
hueIp='IpOfYourHueBridgeHere'
hueApiKey='HueApiKeyHere'
lightId='7'
brightness='254'
time='10000'
lightPut=`curl --request PUT --data "{\"on\":true, \"bri\":$brightness, \"transitiontime\":$time}" http://$hueIp/api/$hueApiKey/lights/"$lightId"/state/`
echo "lightPut:"; echo "$lightPut"


You can find the Hue endpoints, definitions, and more in the Philips Hue API Documentation