Home AutomationHow-To

Getting Started with the Philips Hue REST API

Austen·

The Philips Hue smart lighting ecosystem is robust, flexible, and offers a number of out-of-the-box features that go a long way to delivering a powerful smart home experience.

However, the primary methods for interacting with the system has some limitations that hinder the quest to achieve our true Smart House (1999) vision.

Trust me — it’s not as hard to use as it sounds.

Enter the Hue REST API – a powerful set of tools for developers to expand the functionality of their Hue systems.

An application programming interface, or API, is an interface that defines interactions between different software services. In this case, we want to use the API to bypass the Hue app and directly interact with the Hue Hub to control our lights and sensors.

Philips has opted to use a REpresentational State Transfer, or “REST” API to enable developer interactions. REST APIs use HTTP requests (GET, PUT, POST, and DELETE) to tell the end software what to do.

Trust me — it’s not as hard as to use as it probably sounds. Gaining access to the Philips Hue REST API is the first step to enable you to expand and automate the functions of your smart lights and sensors.

How to Access the Philips Hue REST API

You have a few options for interacting with the Hue API.

  • Your Browser: Since we are just using HTTP, you can run all of these commands via the address bar in your browser
  • Hue Clip API Debugger: You can interact with an interface provided by your Hue Hub at https://<hub IP address>/debug/clip.html
  • A REST API Client: There are many options available, but I recommend the Advanced REST Client Chrome extension

In this guide, I’ll be using the CLIP API Debugger (after step 1)

1. Find the IP address of your Hue Hub

To get started, you need to know the IP address of your hub. The easiest way to get this is via discovery.meethue.com

Go to this link while connected to the same network as your hub, and you’ll get something like this:

[{"id":"001788fffeffe7b7","internalipaddress":"10.0.0.192"}]

Document this IP address somewhere safe. You’re going to use it a lot.

a screenshot of the Hue Hub CLIP API Debugger

2. Create an Authorized User

In order to interact with the API, you need to create an Authorized User.

Navigate to your hub’s CLIP API Debugger by typing the following in your browser:

http://<YOUR HUB IP>/debug/clip.html

In my case, that’s:

http://10.0.0.192/debug/clip.html

You should see a window like the one on the right.

Here, you need to issue a command to create a new authorized user. To do this, fill out the following fields:

        URL: /api
Message Body: {"devicetype":"my_hue_app#iphone austen"}

This command is telling the hub to create a new user in the location /api, where users are stored.

Note that all message content is in JSON (JavaScript Object Notation) format.

Go ahead and click POST. You should get an error that says the Hub Button was not pressed.

Go push it, come back, and click POST again. You’ll get output like the following:

[
    {
        "success": {
            "username": "GI55xM2PlF9LwRtJHN2t0cgh9hQvve5AyN1788KB"
        }
    }
]

Document this username somewhere safe. Like the hub IP address, you’re going to use this a lot.

Important!

This username grants full access to your Hue lighting system. While it is only useful by people who are on your network, I recommend keeping it somewhere safe and secret to keep your smart home secure.

3. Start using the REST API

You now have all of the tools you need to start using the REST API! There are a few things you should know.

To continue using the CLIP interface, replace the URL field with /api/<YOUR USER>/

Generally, querying the system for device and rule lists or current device states is done using GET commands. For example, if you want to get a list of the Sensors in your system, you would put the following into the URL field:

/api/GI55xM2PlF9LwRtJHN2t0cgh9hQvve5AyN1788KB/sensors

Click GET. Your output will look something like this:

{
	"1": {
		"state": {
			"daylight": false,
			"lastupdated": "2020-09-08T01:20:00"
		},
		"config": {
			"on": true,
			"configured": true,
			"sunriseoffset": 30,
			"sunsetoffset": -30
		},
		"name": "Daylight",
		"type": "Daylight",
		"modelid": "PHDL00",
		"manufacturername": "Signify Netherlands B.V.",
		"swversion": "1.0"
	},
	"2": {
		"state": {
			"buttonevent": 3003,
			"lastupdated": "2020-09-08T01:46:40"
		},
		"swupdate": {
			"state": "batterylow",
			"lastinstall": null
		},
		"config": {
			"on": true,
			"battery": 38,
			"reachable": true,
			"pending": []
		},
		"name": "Hue dimmer switch 1",
		"type": "ZLLSwitch",
		"modelid": "RWL020",
		"manufacturername": "Signify Netherlands B.V.",
		"productname": "Hue dimmer switch",
		"diversityid": "73bbabea-3420-499a-9856-46bf437e119b",
		"swversion": "5.45.1.16265",
		"uniqueid": "00:17:88:01:10:33:6a:5c-02-fc00",
		"capabilities": {
			"certified": true,
			"primary": true,
			"inputs": [
				{
					"repeatintervals": [
						800
					],
					"events": [
						{
							"buttonevent": 1000,
							"eventtype": "initial_press"
						},
						{
							"buttonevent": 1001,
							"eventtype": "repeat"
						},
						{
							"buttonevent": 1002,
							"eventtype": "short_release"
						},
						{
							"buttonevent": 1003,
							"eventtype": "long_release"
						}
					]
				},
				{
					"repeatintervals": [
						800
					],
					"events": [
						{
							"buttonevent": 2000,
							"eventtype": "initial_press"
						},
						{
							"buttonevent": 2001,
							"eventtype": "repeat"
						},
						{
							"buttonevent": 2002,
							"eventtype": "short_release"
						},
						{
							"buttonevent": 2003,
							"eventtype": "long_release"
						}
					]
				},
				{
					"repeatintervals": [
						800
					],
					"events": [
						{
							"buttonevent": 3000,
							"eventtype": "initial_press"
						},
						{
							"buttonevent": 3001,
							"eventtype": "repeat"
						},
						{
							"buttonevent": 3002,
							"eventtype": "short_release"
						},
						{
							"buttonevent": 3003,
							"eventtype": "long_release"
						}
					]
				},
				{
					"repeatintervals": [
						800
					],
					"events": [
						{
							"buttonevent": 4000,
							"eventtype": "initial_press"
						},
						{
							"buttonevent": 4001,
							"eventtype": "repeat"
						},
						{
							"buttonevent": 4002,
							"eventtype": "short_release"
						},
						{
							"buttonevent": 4003,
							"eventtype": "long_release"
						}
					]
				}
			]
		}
	},

As you can see, I have a number of Hue Switches and other sensors in my environment.

This section shows me that my Switch, “Hue dimmer switch 1”, is low on battery:

	"2": {
		"state": {
			"buttonevent": 3003,
			"lastupdated": "2020-09-08T01:46:40"
		},
		"swupdate": {
			"state": "batterylow",
			"lastinstall": null
		},
		"config": {
			"on": true,
			"battery": 38,
			"reachable": true,
			"pending": []
		},
		"name": "Hue dimmer switch 1",
		"type": "ZLLSwitch",
		"modelid": "RWL020",
		"manufacturername": "Signify Netherlands B.V.",
		"productname": "Hue dimmer switch",
		"diversityid": "73bbabea-3420-499a-9856-46bf437e119b",
		"swversion": "5.45.1.16265",
		"uniqueid": "00:17:88:01:10:33:6a:5c-02-fc00",
		"capabilities": {
			"certified": true,
			"primary": true,
			"inputs": [
                               ...

I should probably take care of that.

On the flip side, the PUT command will be used to tell your system to do something, like turning on a light.

The full list of available commands and interactions is available on the Philips Hue Developer website. A free login is required – I highly recommend creating one.

Play around with your Hue API and see the possibilities! What do you plan on automating in your environment?

Tags
Austen
Related

7 Comments

  1. Pingback: Dead Simple Light Automation with Home Assistant – AC/M

  2. I know this if off topic but I’m looking into starting my own blog and was wondering what all is needed to get setup? I’m assuming having a blog like yours would cost a pretty penny? I’m not very web smart so I’m not 100 positive. Any suggestions or advice would be greatly appreciated. Thanks

    Reply

    1. Off topic doesn’t mean bad! Thank you for visiting my site.

      You can spend as much or as little on a website as you like. Personally, I use WordPress with a theme that I purchased from ThemeForest for a very reasonable price.

      I’d suggest looking for themes that offer things like layout/page builders and high customizability. I use a lot of custom CSS on this site, but you can do a lot without any code just by using themes that have powerful customization options.

      Let me know if you have any other questions! I’m happy to help – and if you need someone to help build/customize your site, I am available to hire for one-off projects.

      Reply

    1. Hi Dave, sorry for the delayed response here! Did you get this worked out?

      This is possible, yes. From the Hue API documentation, you would be using the “Set group state” endpoints/actions.

      You’re almost there. The documentation shows the URL would end with: /api/{username}/groups/{id}/action

      In your case you need to send the command to the URL you wrote: https://192.168.84.11/api/{username}/groups/1/action

      The body of the message you send to that URL is where the command goes. A sample to turn on the group:

      {
      "on": true
      }

      To set the group state to ‘off’, target the same URL with this body:

      {
      "on": false
      }

      Remember, you can test this by putting the body JSON into the “Message Body:” field of the Clip API Debugger. Or, use a dedicated REST API client (like the Chrome app, Advanced REST Client); or, something like the curl command (see: How to post JSON data using Curl?)

      Refer to the HUE API v1 documentation here: https://developers.meethue.com/develop/hue-api/groupds-api/#set-gr-state

      Reply

  4. Hi, thanks for the blog, this is very useful.

    I have a question which is not 100% related but along the lines of the blog if I may.

    I am trying to use IFTTT such that if my ring doorbell senses motion a hue light turns on and then turns off after a set time. I can get this working, however, I also want to by-pass this command if the light is already on, i.e. don’t turn the light off if I’ve already previously turned it on.

    And so I think I need a way to find the on/off state of a specific light, however, I’m not sure if the hue.getLights[0].Status code query IFTTT suggests quite returns what I need. Any help would be appreciated!

    Reply

  5. Do you know if its possible to revoke or cycle an API key once its created? Do I need to delete and create a new user? How do I do this?

    I suspect I could reset the bridge but I don’t want to have to do that if I can help it…

    Reply

Your email address will not be published. Required fields are marked *