A simple start to using the Hive Home API

If you want to start playing with your Hive Home system, you’re going to need a starting point.  It’s not a difficult thing to do but you need to be a bit methodical about it.

What I’d recommend first is getting postman.  This is a nice little app you can install so that you can send test queries to the Hive API and see what the responses look like.  The real beauty is that you can then generate code in a number of different languages.  Personally, I use Python requests on a Raspberry Pi.  Postman gives me a really good starting point as I’m not really a programmer.  I then add in little bits so that, for example, I can set the heating temperature based on a form input through a web interface rather than having it hardcoded into the JSON payload that I send to Hive.

So, get yourself over to https://www.getpostman.com/ first and install that.

Logging into the Hive API

Before you do anything, you’ll need a session ID from Hive.  You’ll need to send this any time you make API calls.  This will need to be renewed each time you open Postman but all the while you have Postman open and working, your session ID should be valid.  If you get an error saying “Not Authorised” then it’s a good sign that your session ID has expired so you’ll need to authenticate again and get a new one.

First create a new collection.  This like a folder that you put your requests in.

Create a collection first and call it Hive

Next, create a new request using the “New” button in the top left.  Give it a name and choose the “Hive” collection at the bottom.  The first one you need to create is your login so call it “Login”

You just need a name and the location to store your new request.

You’ll now have a screen to build your request.  For your login, you need to set the method to “post”.  By default, it’ll be set to “get”, so change that first.  At the same time, you might as well put the URL in.  For this, the URL is going to be:

https://api.prod.bgchprod.info:443/omnia/auth/sessions

Headers

You’ll need to send some basic info over to Hive to set this up.  In the form at the top, add keys with the names and values as per this screenshot:

Add keys and values for your headers

There’s a button in the top right of this view that says “Bulk edit”.  If you click on this, you should just be able to copy and paste this.  Switch back to “key-value” mode and make sure it looks like the screenshot:

Content-Type:application/vnd.alertme.zoo-6.1+json
Accept:application/vnd.alertme.zoo-6.1+json
X-Omnia-Client:Hive Web Dashboard

Body

Now switch to the “Body” tab.  You can see this in the screenshot above next to “Headers”.

There’s some code below that you need to paste in so that your screen looks like this:

You’ll need to replace the “xxxxx” bits with the username and password you use to login to your Hive account.

This is the code from the screenshot:

{
“sessions”: [{
“username”: “xxxxx”,
“password”: “xxxxx”,
“caller”: “WEB”
}]
}

Now you should be done.  Click on the “Send” button in the top right of the screen.  If everything is good, the bottom of the screen will change and you’ll get a valid response from Hive.  One of the lines in this will be your session ID and will look something like this:

“sessionId”: “rFYc2XXXtk2KIp5PLzzzzzXjHt17NX2Y”

Keep this tab open as you’ll need that session ID in a second.

Getting some data

Now you’ve got that, you’ll want to get some data.  Let’s say you want to get all the events for your sensors.

You’ll need to create a new request in the same way as you did to create your login.  So click on “New” and create a request called “Events” in your Hive collection.

This one is slightly easier because you just need the right URL and headers.  So click on the “Headers” tab, click on “Bulk edit” in the top right and paste this in:

Content-Type:application/vnd.alertme.zoo-6.1+json
Accept:application/vnd.alertme.zoo-6.1+json
X-Omnia-Client:Dashboard
X-Omnia-Access-token:XXXXXXXXXXXXXXXXXX

You’ll need to go back to your login tab now and grab that session ID.  Paste that in where I’ve put the X’s.

You can leave the method as “get” for this request as you’re not sending any actual data, just asking for information.  In the URL field, put this in:

https://api-prod.bgchprod.info:443/omnia/events

Now click “Send” again.  You should get a big bunch of data back in the bottom of the screen with all the events from your sensors.  For me, it tells me things like this:

{
“id”: “xxxxxxx”,
“href”: “https://api-prod.bgchprod.info/omnia/events/xxxxxxx”,
“eventType”: “MOTION_DETECTED”,
“source”: “yyyyyyy”,
“time”: “2018-12-08T10:27:22.582+0000”,
“home”: “zzzzzzz”
}

I’ve just replaced any real values to anonymise my data but you can see that motion was detected at about 10:27 on the 8th December 2018.

As a last little exercise, create a new “get” request with the URL:

https://api-prod.bgchprod.info:443/omnia/nodes

Add in the headers (switch to bulk edit) and paste this in, changing the x’s to the session ID you got when you logged in:

Content-Type:application/vnd.alertme.zoo-6.1+json
Accept:application/vnd.alertme.zoo-6.1+json
X-Omnia-Client:Hive Web Dashboard
X-Omnia-Access-Token:xxxxxxxxxxxxx

Press send.

In the bottom of the screen you’ll get every bit of information about every device you have.  Scroll through this and you’ll eventually see your thermostat if you have one.  If you know the name, there is a search function.  Your thermostat will have an id which will look something like this:

0e5f20fb-ab13-4d43-89ed-ec248xxxxxxx

Now, if you add that – or the id of any other device you find – onto the end of the URL for this request, you’ll see just the information about that device.  Change the URL for this request to:

https://api-prod.bgchprod.info:443/omnia/nodes/0e5f20fb-ab13-4d43-89ed-ec248xxxxxxx

Remember to replace the bit after node/ with the id of your device and press send again.  You’ll now see just the info about your thermostat if that’s the device you found.

For example, part of the data that I see is:

“temperature”: {
“reportedValue”: 20.41,
“displayValue”: 20.41,
“reportReceivedTime”: 1544265421660,
“reportChangedTime”: 1544265421660
},

So that’s telling me what my current internal temperature is.

Hopefully, that should get you started.  The Hive API isn’t very well documented but there are a few sites out there that might help.  My starting point was http://www.smartofthehome.com/2016/05/hive-rest-api-v6/

This has loads more information than I’ve got here but it I think my guide is probably a bit more basic.  If you’re right at the start, my guide will get you going and the smart of the home site will get you to the next steps such as writing back to Hive to set your temperature or turn lights on and things.

I’ve now got my own dashboard specifically for some of the heating functions that you can see below.  My motivation for this was occupancy detection.  I’ve got another blog post about this but in brief terms, the 4 squares in the left column show who’s in and who’s out.  I’m “A” and I’m out.  Consequently, the heating temperature is set to 18 degrees.  You can also see that “auto” is off.  When this is on, it overrides the schedules on Hive and just uses occupancy detection.  In my case, if I was at home then it would set the heating to my preferred temperature of 21 degrees.  The middle column has the buttons for turning the temperature up or down, turning boost on or turning the auto mode on.  The right shows a feed from a Raspberry Pi security camera and the outside temperature.

Now I’ve got this started, it’s growing all the time.  There might be other solutions out there but I enjoy the challenge.  I haven’t seen anything else that does the occupancy detection for Hive so I guess I’m ahead of the game for that one!

Custom built dashboard for Hive Home running as a webview app on a Kindle Fire HD