Hive REST API v6.1

105 thoughts on “Hive REST API v6.1”

1. 

   Chris Foot says:

   Unfortunately, it seems that the urls mentioned (https://api.prod.bgchprod.info) no longer work correctly as the ssl on that domain is invalid, however, a small change to https://api-prod.bgchprod.info works fine.

   7 September 2016 at 19:34

   Reply
2. 

   James Saunders says:

   Hi Chris, thanks for the updated URL. I will modify this blog post to suit.

   7 September 2016 at 19:47

   Reply
3. 

   John says:

   Is it possible to get the current temperature with the 6.1 API?

   14 October 2016 at 20:45

   Reply
   • 

     James Saunders says:

     @John Yes sure,
     GET device thermostat will return current temperature….
     “temperature”: {
     “reportedValue”: 20.07,
     “displayValue”: 20.07,
     “reportReceivedTime”: 1476480696281,
     “reportChangedTime”: 1476480696281,
     “readOnly”: false
     },

     14 October 2016 at 22:35

     Reply
     • 

       Paul says:

       I wasn’t able to get this to work can you give url you used

       31 October 2016 at 17:42

       Reply
       • 

         James Saunders says:

         Hi Paul, what did you not get to work? The base URLs are above. If you are wanting to get the current temperature note you need to pull the values on the Hive receiver (not the thermostat as you may first assume).
         Jim

         31 October 2016 at 19:36

         Reply
         • 

           Paul says:

           Sorry got a bit confused I couldn’t find temperature in your example for nodes so assumed it was another method. I have succeeded in finding the current temperature by using nodes as method. I was also able to reduce the 2411 line response to 643 by putting /id of receiver after nodes don’t suppose its possible to get just an attribute returned as this api response is rather heavy for a small embedded device to use. shame they haven’t followed other IOT platforms and given a user configured api so it looks like I might have to create my own restapi wrapper on another Device.

           1 November 2016 at 11:46
4. 

   Paul says:

   Great work James

   Been playing with the API today calling it from inside an oracle database.

   So far managed to get the authentication working to get my session id and then calling the nodes successfully, parsing the json and displaying it in an APEX application which is a nice start but still plenty more I can try. I noticed it’s actually the Heating Receiver you retrieve the temperature from and not the thermostat.

   Seems like a lot will be possible. I saw a feature request on the Hive forums from someone to overlay the temperature graph with when the boiler was actually firing which I thought would be pretty nice and I reckon as you can retrieve past actual temperatures and target temperatures that it would certainly be possible to do.

   Shame there’s no API for the BG smart meters as I’ve just had them installed.

   30 October 2016 at 18:27

   Reply
5. 

   Martin says:

   Hi,I have just have Hive installed and I have been trying to access the web API using an Chrome test App called Postman.
   I send a Post to
   https://api-prod.bgchprod.info:443/omnia/auth/sessions
   with raw body
   {
   “sessions”: [{
   “username”: “xxxxxxxxxx@xxxxxxxxx”,
   “password”: “xxxxxxxxxxxx”,
   “caller”: “WEB”,
   “Accept”: “application/vnd.alertme.zoo-6.1+json”,
   “Content-Type”: “application/vnd.alertme.zoo-6.1+json”,
   “X-Omnia-Client”: “Hive Web Dashboard”
   }]
   }
   with or without Content-Type application/json in the header, but I always get back
   {
   “error”: {
   “reason”: “COULD_NOT_PARSE_VERSION”,
   “message”: “Please provide API version in Accept header in the format e.g.: ‘application/vnd.alertme.zoo-6.0.0+json’. The known versions are: [6.0, 6.1, 6.2, 6.3, 6.4, 6.5]”
   }
   }

   The username and password work ok with the V5 APi login, any idea where I am going wrong. Thanks for any help.

   2 November 2016 at 00:07

   Reply
   • 

     James Saunders says:

     Hi Martin,

     As it happens, I have put together a couple of Postman ‘collections’ for the Hive v5 and v6.1 API’s which may be of use.

     Postman is a really cool Chrome extension application which allows you to test REST API’s and save them into a library. You can download Postman here:
     https://www.getpostman.com

     Once installed you should then be able to add the following ‘Collections’ to your Postman app:
     * Hive API v5 https://www.getpostman.com/collections/b07ceeb5983e7640b07e
     * Hive API v6.1 https://www.getpostman.com/collections/954a62af1259222e8b39

     I have configured these to use session variables and it should populate variables such as hubId and sessionId automatically on login, but You may need to configure your own environment variables for:
     “v6url” : “https://api-prod.bgchprod.info:443/omnia”
     “v5url” : “https://api.bgchlivehome.co.uk/v5”
     “username” : “user@email.co.uk”
     “password” : “pa$$word”

     If you find these useful or have and additions or corrections please do share your ideas – I am happy to add further to these. I may pop them on GitHub to share.

     2 November 2016 at 07:05

     Reply
     • 

       Martin says:

       Hi James, Thanks for the quick reply, I see my problem now, I was putting the Accept etc in the body instead of the headers. Thanks for the help

       2 November 2016 at 17:58

       Reply
     • 

       Graham White says:

       Hi James,

       Thanks for your work on this. Having bought a Google Home back to the UK from the US this weekend I’ve been investigating setting it up with Hive since IFTTT support for Hive is rather basic. Ultimately, I’d like to create a Node Red node for version 6.1 of the API and this guide has given me a great head start.

       Playing around with your Postman collection for v6.1 you’ve included your device ID in the URL. It’s no biggie but you could add a variable for that as well based off the GET call to Device List.

       Thanks again,

       Graham

       7 November 2016 at 15:13

       Reply
     • 

       Steve says:

       Great work. How about adding requests for lights?

       22 November 2016 at 22:14

       Reply
       • 

         James Saunders says:

         Thanks Steve,
         I haven’t got any Hive bulbs yet, but I am sure it will not be a million miles from that of ‘THERMOSTAT SET’ calls above. So would probably be something like:

         [PUT] /nodes/xxxx-light-node-id-xxxxx
         Request Body:
         {
         “nodes”: [{
         “attributes”: {
         “state”: on,
         “level”: 90
         }
         }]
         }

         The above is only a guess – but you get the idea.

         22 November 2016 at 22:47

         Reply
         • 

           Steve says:

           Cheers James,
           I installed the postman interceptor (it’s great!) and found for my white bulb it’s the following:
           {
           “nodes”:[{
           “attributes”:{
           “state”:{“targetValue”:”ON”},
           “brightness”:{“targetValue”:100}
           }
           }]
           }

           Seems the ON/OFF *has* to be uppercase
           … off to play with the colour bulb now 🙂

           26 November 2016 at 15:43
         • 

           Steve says:

           …and from a colour bulb it’s all about hue, saturation and value as a colour,brightness:
           {
           “nodes”:[{
           “attributes”:{
           “hsvHue”:{“targetValue”:0},
           “hsvSaturation”:{“targetValue”:99},
           “hsvValue”:{“targetValue”:100},
           “colourMode”:{“targetValue”:”COLOUR”}
           }
           }]
           }

           26 November 2016 at 18:25
         • 

           James Saunders says:

           Perfect, thanks for feeding back Steve, this will really help others. Jim

           26 November 2016 at 19:47
         • 

           Alex says:

           For a White To Warm bulb if you want to set colour temp and brightness:

           {
           “nodes”: [{
           “attributes”: {
           “state”: {
           “targetValue”: “ON”
           },
           “brightness”: {
           “targetValue”: 90
           },
           “brightnessTransitionTime”: {
           “targetValue”: “”
           },
           “colourTemperature”: {
           “targetValue”: 3378.3783783783783
           },
           “colourTemperatureTransitionTime”: {
           “targetValue”: “”
           }
           }
           }]
           }

           Simple on off operation is the same as the active plug call

           14 December 2016 at 21:26
     • 

       Keith Solomon says:

       Sorry to dredge up an old post, but I just got my Hive kit. I want to use one of the active plugs to control power to my 3D printer, so I’ve been poking around the API. However, I’m having a problem where no matter what I do, I always get a USERNAME_PASSWORD_ERROR when trying to authenticate. I’m using your v6.1 collection in Postman, with the proper environment variables configured, but it happens even without the collection. Any pointers on where to start looking to track down the issue?

       5 July 2017 at 18:57

       Reply
6. 

   Will says:

   Thanks for this. I’ve been trying to find a response which includes basic info about Hive’s heating – mainly, when did the heating last come on? What was the time when it went off? I may have missed it in /nodes/ but can’t see that anywhere. Have you come across it?

   25 November 2016 at 22:05

   Reply
   • 

     James Saunders says:

     Hi Will,
     I think what you are looking for can be found in the ‘channels’ function. I briefly talk about this call above in this post. If you first off do a GET call to:
     /channels/
     You will then receive a list of available channels akin to:
     {
     “id”: “controllerState@2ba0f1e4-4f51-4aea-adb3-447908448786”,
     “href”: “https://api.prod.bgchprod.info:8443/omnia/channels/controllerState@2ba0f1e4-4f51-4aea-adb3-447908448786”,
     “links”: {
     “node”: [
     “2ba0f1e4-4f51-4aea-adb3-447908448786”
     ]
     },
     “unit”: “ENCODED RELAY STATE”,
     “supportedOperations”: [
     “DATASET”
     ]
     },

     Then a call to /channels/controllerState@2ba0f1e4-4f51-4aea-adb3-447908448786?start=1458432000000&end=1459360868000&rate=5&timeUnit=MINUTES&operation=DATASET

     You will see results akin to:
     {
     “meta”: {},
     “links”: {},
     “linked”: {},
     “channels”: [
     {
     “id”: “controllerState@2ba0f1e4-4f51-4aea-adb3-447908448786”,
     “href”: “https://api.prod.bgchprod.info:8443/omnia/channels/controllerState@2ba0f1e4-4f51-4aea-adb3-447908448786”,
     “links”: {
     “node”: [
     “2ba0f1e4-4f51-4aea-adb3-447908448786”
     ]
     },
     “start”: 1458432000000,
     “end”: 1459360868000,
     “timeUnit”: “MINUTES”,
     “rate”: 5,
     “timeZone”: “Europe/London”,
     “unit”: “ENCODED RELAY STATE”,
     “values”: {
     “1458432000000”: 0,
     “1458432300000”: 0,
     “1458432600000”: 0,
     “1458481200000”: 0,
     “1458481500000”: 1,
     “1458481800000”: 1,
     “1458482100000”: 1,
     “1458482400000”: 0,

     Hope this helps.

     25 November 2016 at 22:34

     Reply
     • 

       Rick says:

       Hi James,
       Have you any idea what the returned values relate to from call to the controllerstate? only I get back values of 0,1,2 and 3?

       31 March 2017 at 12:49

       Reply
7. 

   Daniel says:

   Hi, I was wondering if anybody knows how we can control Hive Active Lights through the API, if possible does anybody have details on how to do this in both v5 and v6 APIs?

   Also, I noticed the v6 API now lets us activate a Boost. Does the v5 allow this in some way? If so it would be useful so I don’t have to re-write my code that calls the API. If anybody could offer any advice that would be great.

   19 December 2016 at 15:41

   Reply
   • 

     James Saunders says:

     Hi @dan
     For v6 API see the comment from Steve 26 November detailing the call needed to control lights.
     As for v5, I doubt it is possible as the bulbs came about after this API version so doubt they added this support.

     Hope this helps.

     19 December 2016 at 19:20

     Reply
     • 

       Daniel says:

       Thanks, sorry I missed that comment somehow. I’ve got the basics working with lights now (Only have a White Bulb to test with tbh) and just using a mix of the v5 and v6 API in the same solution at the moment. I didn’t realise the v6 API existed until after writing all the code based on v5.

       Good to see Boost is in the v6 API too. I am looking into how to rename a node at the moment so if I figure out that it’s possible I’ll post here. I’ll have to have a proper dig through the documentation at the link you provided.

       Thanks again for publishing this post, your v5 post was also a big help.

       21 December 2016 at 10:37

       Reply
8. 

   Craig says:

   Hi James, superb article,
   However I am getting the following response:

   {“errors”:[{“code”:”INVALID_PARAMETER”,”title”:”No such properties ‘[state]’ in class ‘com.alertme.zoo.schemas.Node_class_synthetic_binary_control_device_uniform_scheduler”,”links”:[]}]}

   When I issue a PUT to try and access a smart socket using the request

   {
       “nodes”: [{
           “attributes”: {
               “state”: {
                   “targetValue”: “ON”
               }
           }
       }]
   }

   Do you have any advice?

   2 January 2017 at 00:44

   Reply
   • 

     James Saunders says:

     Hi Craig, I think your call looks correct, but the device you are calling it against is possibly incorrect?
     In your example it says the class nodeType is:
     “nodeType”: “http://alertme.com/schema/json/node.class.synthetic.binary.control.device.uniform.scheduler.json#”,
     where as an ActivePlug class nodeType should be:
     “nodeType”: “http://alertme.com/schema/json/node.class.smartplug.json#”
     I think you are making the call against the synthetic (virtual) scheduler device rather than the physical ActivePlug device.

     Check the device ID you are calling this against.

     I also assume you are trying to control a new Hive ActivePlug (rather than the older AlertMe SmartPlug which can not be remotely controlled)?

     2 January 2017 at 09:31

     Reply
9. 

   Kieron Cooke says:

   Hi James, useful article, wondered if anyone could clarify my understanding of the nodes listed in the output of get nodes. For me I just have one thermostat, but I get list of 5 nodes back:

   1) “name”: “Home”,
   “nodeType”: “http://alertme.com/schema/json/node.class.thermostat.json#”,

   2) “name”: “Your Receiver”,
   “nodeType”: “http://alertme.com/schema/json/node.class.thermostat.json#”,

   3) “name”: “http://alertme.com/schema/json/node.class.synthetic.zonename.initializer.json#”,
   “nodeType”: “http://alertme.com/schema/json/node.class.synthetic.zonename.initializer.json#”,

   4) “name”: “Home”,
   “nodeType”: “http://alertme.com/schema/json/node.class.thermostatui.json#”,

   5) “name”: “Your Hub”,
   “nodeType”: “http://alertme.com/schema/json/node.class.hub.json#”,

   I’ve been playing with setting the activeHeatCoolMode on the node named “Your Receiver”, which broadly seems to work, not always consistently though. Any idea what the second node of the same type is for? Both have the attribute: “activeHeatCoolMode”, should I be setting both?

   9 January 2017 at 11:45

   Reply
   • 

     James Saunders says:

     Hi Kieron,
     The nodes you are seeing are:
     1) “name”: “Home” – This is your thermostat, the unit with the controls and screen (You probably renamed it to ‘Home’ in your Hive app).
     2) “name”: “Your Receiver” – This is the receiver which sits next to, and connects directly to, your boiler.
     3) “name”: “Synthetic” – This is a virtual device, it is the scheduler which you can use to set boiler on/off schedules.
     4) “name”: “Home” – Not sure why you see 2 of these??
     5) “name”: “Your Hub” – Your hub device connected to your broadband router.

     I too was a little confused by all these at the start as it is a little backwards, but when setting temperature though the API you send temperatures to the ‘Receiver’ device (not the ‘Thermostat’ as you would first assume). The way I remember it is that the ‘Receiver’ device is the main boiler control brain which can be sent messages from either the Hub (via Web/API) or from the Thermostat (via Zigbee) or from the Synthetic virtual schedule device. Hope this makes sense.
     Jim

     11 January 2017 at 21:40

     Reply
     • 

       Kieron Cooke says:

       Thanks James for the clarification. In case this of any use to others, I’ve written a small program to turn my heating schedule on/off based on whether any mobile phones (and therefore people) are at home. Its always been a bit of a frustration to me that the mobile app just sends me geo-location alerts rather than actually doing something about it. Anyway take a look: https://github.com/krcooke/hive-home

       11 January 2017 at 23:01

       Reply
       • 

         Steve says:

         Awesome that you shared the code, thanks

         12 January 2017 at 00:03

         Reply
10. 

    John Maguire says:

    I’ve been trying to use this tread as a means of controlling my two new Hive lights. If nothing else I’ve learnt a lot about PUT and GET but now I’ve fit a brick wall.

    So using Postman I can login OK and get back the session ID token, I can also get a Device list and receive two ids for the two bulbs I have.

    I can even send a GET …./nodes/0967bc11-7462-448a-87fe-bac199920f07 referencing the ID of one of the bulbs and I get the following (snipped to remove the irrelevant stuff)

    “meta”: {},
    “links”: {},
    “linked”: {},
    “nodes”: [
    {
    “id”: “0967bc11-7462-448a-87fe-bac199920f07”,
    “href”: “https://api.prod.bgchprod.info:8443/omnia/nodes/0967bc11-7462-448a-87fe-bac199920f07”,
    “links”: {},
    “name”: “Warm White 1”,
    “nodeType”: “http://alertme.com/schema/json/node.class.light.json#”,
    “parentNodeId”: “64ae687e-949e-4218-9b05-14aa3ea8c8d8”,
    “lastSeen”: 1484571060158,
    “createdOn”: 1484383859437,
    “userId”: “xxxxx”,
    “ownerId”: “xxxxxx”,
    “relationships”: {
    “boundNodes”: []
    },

    },
    “brightness”: {
    “reportedValue”: 100,
    “targetValue”: 100,
    “displayValue”: 100,
    “reportReceivedTime”: 1484401860316,
    “reportChangedTime”: 1484389412177,
    “targetSetTime”: 1484389998156,
    “targetExpiryTime”: 1484390298156,
    “targetSetTXId”: “540f84df-0779-4b42-a591-59d0bc991d53”,
    “propertyStatus”: “COMPLETE”

    “model”: {
    “reportedValue”: “FWBulb01”,
    “displayValue”: “FWBulb01”,
    “reportReceivedTime”: 1484401860316,
    “reportChangedTime”: 1484383859357
    },
    “state”: {
    “reportedValue”: “OFF”,
    “targetValue”: “OFF”,
    “displayValue”: “OFF”,
    “reportReceivedTime”: 1484401860316,
    “reportChangedTime”: 1484389999266,
    “targetSetTime”: 1484389998156,
    “targetExpiryTime”: 1484390298156,
    “targetSetTXId”: “540f84df-0779-4b42-a591-59d0bc991d53”,
    “propertyStatus”: “COMPLETE”
    },
    …snip…

    So it seems to be reporting back OK

    But if I try to change the status by sending a PUT to …./nodes/0967bc11-7462-448a-87fe-bac199920f07

    With the following in the body
    {
    “nodes”:[{
    “attributes”:{
    “state”:{“targetValue”:”ON”},
    “brightness”:{“targetValue”:100}
    }
    }]
    }

    I always get a 400 error ‘Could not read json”

    I’ve tried both the bulb IDs, different browsers and plugins (both on a PC and Mac) but always get the same result.

    I’d be grateful if anyone could point out where I’m going wrong – I’m probably doing something obviously incorrect.

    Many thanks in advance

    16 January 2017 at 13:41

    Reply
    • 

      James Saunders says:

      Hi John,
      What happens when you paste your request into a JSON validator like http://jsonlint.com/ ? Does it validate OK?

      My first guess is that the quotes you are using are “ (unicode quotes) rather then ” (ascii quotes) ?
      e.g “targetValue”:”ON” rather than “targetValue”:”ON”.

      [EDIT]… ahh, thats annoying WordPress converts them.. But I think you get the idea – replace your quotes.

      16 January 2017 at 14:52

      Reply
      • 

        John Maguire says:

        Oh for crying out loud! That’s what happens when you copy and paste!

        Right then I’ve manually retyped all the quotes, dropped the whole body content into a JSON validator (the one you suggested) and it returns OK.

        So far so good, try to send the PUT command and I get a 404 error and the return result is
        “errors”: [
        “code”: “NOT_FOUND”,
        “links”: []
        I’ve snipped some of the opening and closing braces out

        Which sounds to me as if the target URL is wrong. I can successfully run a GET command to URL/nodes/
        as from the results returned from a Device List GET command below;

        “id”: “0967bc11-7462-448a-87fe-bac199920f07”,
        “href”: “https://api.prod.bgchprod.info:8443/omnia/nodes/0967bc11-7462-448a-87fe-bac199920f07”,
        “links”: {},
        “name”: “Warm White 1”,
        “nodeType”: “http://alertme.com/schema/json/node.class.light.json#”,
        “parentNodeId”: “64ae687e-949e-4218-9b05-14aa3ea8c8d8”,
        “lastSeen”: 1484581859956,
        “createdOn”: 1484383859437,

        Many thanks for your very quick response and I do appreciate any suggestions you might have for me.

        John

        16 January 2017 at 16:31

        Reply
        • 

          John Maguire says:

          Right scrub that, all working now. Turns out that while I was working on the code, someone had managed to switch the bulb off at the switch so no power to it!

          So learnt something new, a 404 Not Found error can mean that the actual device is unreachable.

          And now to learn how cURL works, wrap it all up in bit of Python script and see if my Domoticz HA system can talk to it.

          What can possibly go wrong….

          16 January 2017 at 20:53

          Reply
11. 

    Rick says:

    Hi James,
    Great write up!. I’m looking to just receive the temperature history from this method as the V5 method has stopped working using the call https://api.bgchlivehome.co.uk/v5/users/email@address/widgets/temperature/::xxx:xxxx:xxx:xxxx/history?period=today
    Is this possible with V6?

    27 January 2017 at 11:33

    Reply
    • 

      James Saunders says:

      Hi Rick,
      Sure! See the ‘Channels’ example above from which you can get temperature history.
      Channels are a bit more complicated than the old v5 method but a great deal more powerful.
      Let me know how you get on.
      Jim

      27 January 2017 at 12:33

      Reply
12. 

    Rick says:

    James,
    Thanks, worked out it, thanks. Postman for chrome is a brilliant util, thanks for the heads up.

    27 January 2017 at 15:52

    Reply
13. 

    Kostas says:

    Hello James,

    Thanks for the detailed outline of the API! It is amazing!

    When I experiment with my Hive at home I get an interesting response when asking the nodes! I get 3 entries with name: “Your Receiver” plus “Your Hub” and the UI as “Hive 2”!

    Those 3 entries seem similar but it seems they are doing different things and the only way I could ‘identify’ the one that actually controlled the temperature has been trying to search for the [‘attributes’][‘capabilities’][‘reportedValue’][0] = “THERMOSTAT” but don’t know if this is the most reliable way?

    Thanks!

    5 February 2017 at 19:46

    Reply
14. 

    John says:

    Great article thanks.
    I cant see anything obvious in the outputs but does anyone know of a way to get thermostat battery life from the API?

    17 February 2017 at 16:39

    Reply
    • 

      James Saunders says:

      Hi John, sure, the battery state is there in the device attributes:
      “batteryState”: {
      “reportedValue”: “FULL”,
      “reportReceivedTime”: 1465151979713
      },

      17 February 2017 at 19:41

      Reply
      • 

        John says:

        James, thanks for that. I did see this however as it was against a different device than my thermostat i wasn’t sure what it was related to,

        18 February 2017 at 20:14

        Reply
15. 

    Mike says:

    Hello! Is it possible to check boiler on/off (ie firing or not firing) status with the API. I want to check every minute to be able to create a log of how many hours the boiler has been on for each day…. Thanks

    18 February 2017 at 07:10

    Reply
    • 

      James Saunders says:

      Hi Mike, sure, you can get the thermostat relay state history , see my comment above 25 November 2016 to will. It is achieved using the channels call.

      18 February 2017 at 08:09

      Reply
16. 

    Nick Boyle says:

    I’m trying to set my temperature, and have it all working until the final set call …

    “{“errors”:[{“code”:”MISSING_PARAMETER”,”title”:”Node type is missing”,”links”:[]}]}”

    I didn’t see that I needed to send Node Type. Any suggestions on where to place this and whether this is the right data?

    msg.nodeType = “http://alertme.com/schema/json/node.class.thermostat.json#”;

    msg.payload = {
    “nodes”: [{
    “attributes”: {
    “targetHeatTemperature”: {
    “targetValue”: 22
    }
    }
    }]
    };

    28 March 2017 at 12:11

    Reply
    • 

      James Saunders says:

      Hi Nick, Very odd. You should not need to send a device type?

      1. Are you calling the correct URL? and using PUT?
      e.g: https://api-prod.bgchprod.info:443/omnia/nodes/2ba0f1e4-4f51-4aea-adb3-447908448786

      2. Are you calling against the correct device ID?
      Note: It is a not obvious, but it is NOT the “Your Thermostat” device you send temperature changes to but rather the “Your Receiver” device.

      3. You could try downloading Postman (https://www.getpostman.com/) and the ‘collection’ I have put together to test the Hive API (see comment above dated ‘2 November 2016’ for more info. I have just re-tested the Thermostat Set function on my setup and it all still works fine.

      Let me know how you get on.

      28 March 2017 at 20:45

      Reply
      • 

        Nick Boyle says:

        James,

        3/ I’ve tried Postman, but am unsure how to implement the usernames & passwords. Do you know of a demo?

        2/ I got seven options, so am not sure.

        3 x Your Receiver
        1 x Signal Booster
        1 x schema/json
        1 x Your Hub
        1 x Your Thermostat

        1/ It’s a right mish mash of GET/PUT/PUSH

        29 March 2017 at 00:20

        Reply
17. 

    Ben Davies says:

    Great article James, and thanks for this! It has really helped me get started with my attempt at wrapping the as a PowerShell Module available here if anyone is interested: https://github.com/ukbendavies/PoshHive. I’m hopeful others will find what I’ve started useful and I can highly recommend using the /events api to review how you nodes are interacting and what commands are doing. Thanks, and by the way has anyone successfully attempted to simulate a device using the api to see how the other Hive devices interact?

    28 March 2017 at 21:49

    Reply
    • 

      Ben Davies says:

      Hi James, I’m wondering if it would be possible to get a mention (really small one 🙂 in your main article to help publicise the powershell module. I’ve gotten most functions working now and I’m hoping this will help others with using the API directly too as you can add the -Verbose onto any function and see what the actual API call looks like and this could then be used verbatim in other apps. I’ve also referenced your great work in my module too, hope that’s okay.

      2 April 2017 at 16:38

      Reply
    • 

      Ben Davies says:

      Anyone noticed the change in the 6.5 version of the api recently? attributes has been replaced with features amongst other changes that look like a huge overhaul.

      7 April 2017 at 09:30

      Reply
      • 

        James Saunders says:

        Hi Ben!
        Ooo good spot! It looks like v6.5 is a bit of a change! Ill have to have a play. We may have to write up another post on this new version!

        7 April 2017 at 20:47

        Reply
        • 

          Ben Davies says:

          looks like the hive website is already using these feature based apis. wonder if this unlocks any more functionality.

          I’m looking for a method to monitor boiler water return temperature, not sure if this is possible but I figure if it is its burred in the data somewhere, anyone any clues if this is possible at all please?

          11 April 2017 at 10:10

          Reply
          • 

            Paul says:

            the hive does not even know when the boiler is on as it only raises the demand for the boiler but if its internal stat says water in system is up to temperature then the hive will report the boiler is on when its not. the former alertme products all reported temperature but not sure if the bgas ones do or if its reported in this api but if it did you could attach say a door contact to the return pipe to report temperature.

            11 April 2017 at 10:24
          • 

            Ben Davies says:

            thanks Paul. Are you saying that the AlertMe products did provide diagnostic data from the boiler but Hive does not? I’m looking for water flow temperatures. Question is if my boiler is not emitting the data but others do? and secondly if Hive retrieves this data and makes it available?

            11 April 2017 at 10:53
          • 

            Paul says:

            Alertme did a burglar alarm system which bgas are now offering updated versions of the same sensors ( movement and door contacts ) a feature of the previous alertme sensors was each one reported the temperature of the sensor so the off the wall idea was if the updated bgas door contact does report temperature via the api you could attach a door sensor to your pipes. unfortunately bgas have removed some of the features of the previous alertme products like the power plug doesn’t report power only switches and acts as range extender so they may have removed the temperature reporting from the door sensors even if the hardware still measures it. If someone has any of the door sensors installed maybe they can check if temperature is reported in the api return

            11 April 2017 at 11:06
18. 

    Rick says:

    When I do the following call to get the data for when the heating has been off/on, I’m only getting data back for every 1 hour and not 5 minutes as specified in the call??. Anyone else get this?, am I doing something wrong?.

    /channels/controllerState@2ba0f1e4-4f51-4aea-adb3-447908448786?start=1458432000000&end=1459360868000&rate=5&timeUnit=MINUTES&operation=DATASET

    8 April 2017 at 07:40

    Reply
    • 

      James Saunders says:

      Hi Rick, looks right to me. Are you making this call to the right device? It should be against the receiver not the thermostat device.

      10 April 2017 at 07:46

      Reply
19. 

    Mark says:

    Hi all. I have successfully managed to ‘PUT’ BOOST mode and set temperature from the postman calls. I am struggling to switch between ACTIVE SCHEDULE / OFF / MANUAL / UNBOOST.
    Has anyone managed to find the combination of targets to set these modes?

    9 May 2017 at 22:35

    Reply
    • 

      Jason says:

      Hi did you manage to get an answer to your question, this is the sort of thing I’m trying to find out too?

      16 July 2017 at 06:34

      Reply
20. 

    Filip Stanis says:

    It seems there’s a new version of the API which the web app now uses.

    I went ahead and created a Go library and a command line tool to work with Hive devices (lights and motion sensor for now).

    CLI: https://github.com/fstanis/hivecli
    Library: https://github.com/fstanis/go-hive

    Feedback is welcome!

    29 May 2017 at 21:22

    Reply
21. 

    Graham White says:

    My NodeJS library is now published at https://github.com/grahamwhiteuk/bg-hive-api-v6 although at the moment it’s very basic and only supports read-only methods to get the various statuses of the heating and hot water systems.

    31 May 2017 at 21:51

    Reply
22. 

    Jim says:

    New API URLs ?:
    def apiBeekeeperUKURL(path = ‘/’) { return “https://beekeeper-uk.hivehome.com:443/1.0${path}” }
    def apiBeekeeperURL(path = ‘/’) { return “https://beekeeper.hivehome.com:443/1.0${path}” }

    These were found in the SmartThings Hive Connect code.
    https://community.smartthings.com/t/release-hive-connect-v2-6-british-gas-hive/29492

    2 September 2017 at 10:22

    Reply
23. 

    Mike says:

    I’ve had an Alertme system for years, but they’re turning of the service at the end of October, I’ve been offered a free upgrade to Hive with a few bits (not enough to replace my alertme kit). Does anyone know if the Alertme bits work with the latest Hive hub. Also, does the API still work. I’ve spoken to support but the answer I get is no to both, which I find hard to believe. All I want to do is turn lights on and off via a computer sitting in the house – presumably the API has to go through their servers, so I can’t do the lights locally?

    23 September 2017 at 17:02

    Reply
24. 

    g says:

    I’m looking into using the API to record consumption and temperature data and then also utilise motion detection status changes for use alongside other smart devices, but in order to do this (with the REST API) Long Polling seems like the only option. For this to be responsive I’d need to request every few seconds, but I’m guessing that I’d get blocked in doing so, has anyone tried something similar?

    6 October 2017 at 20:55

    Reply
25. 

    Mike G says:

    This is awesome thank you.
    Some things I’m going to work on – but others may have got there before me:
    Has anyone found a way to get the same information from a local device rather than going out to the internet?
    Any way to subscribe to a stream of updates for a channel rather than polling (though poling every few minutes will probably work)
    Joining the zigbee network with Xbee to get the same information locally.

    28 November 2017 at 13:23

    Reply
26. 

    Tom says:

    James, this is brilliant!!!
    Great, really comprehensive article, and I managed to get it all working using a bash script and curl within an hour or two having had little API experience before.

    One minor point – would it be possible to have the JSON output in expandable boxes as it adds unnecessary length to the page and makes it difficult to find the various URIs that you can GET and PUT to.

    6 December 2017 at 17:40

    Reply
27. 

    Sian says:

    Thanks for a really useful guide to the Hive API.
    I can login successfully, read the nodes and read the channels.
    But when trying to read temperature , using the url:
    https://api.prod.bgchprod.info:8443/omnia/channels/temperature@?start=1518733250396&end=1518733250996&rate=1&timeUnit=MINUTES&operation=AVG
    where end is now and start is 6 minutes ago, I get this response:
    { “errors”: [ { “code”: “NOT_FOUND”, “title”: “No data found for period”, “links”: [] } ] }
    Am I trying to read from the right node? If so, how do I find a valid time range?

    16 February 2018 at 22:27

    Reply
28. 

    Paul Bloomfield says:

    Thanks for this, it inspired me to build a web app to download CSV files of temperature history. This app is available on an as-is basis at https://nothive.uk.

    21 March 2018 at 13:49

    Reply
    • 

      James Saunders says:

      Wow! This is awesome! Well done!

      12 May 2018 at 21:54

      Reply
29. 

    Paul says:

    have had a few problems with the session id which times out after a while of inactivity. you then get a 401 not authorized and if you then ask for a new key it wont give you one just carries on with giving 401. this is running on exosite’s script engine so not easy to work out what is happening as I cant sniff the traffic. by accident I discovered that if you send a request without a session key it will then let you have a new session key on the next request. Is there a better way to get a new session key when it expires due to inactivity

    8 April 2018 at 12:49

    Reply
30. 

    Manigandan says:

    Hi,
    We are facing issue with Hive thermostat latest API response.
    We are not getting the lastSeen value in the API response for the parent node.
    Is it new behaviour or something to do with thermostat??
    “parentNodeId”: “c9c78b80-574c-4ceb-b149-df02e18d2056”,
    “lastSeen”: 1465759250499,

    12 April 2018 at 13:10

    Reply
31. 

    AJ says:

    I’m not an expert programmer but I’d be interested to know from anyone who is how difficult it would be to write something that would turn off the heating when the last person leaves the house, and back on when the first person returns.

    My biggest annoyance with Hive is that they won’t provide the functionality to do proper geofencing like Tado and Nest do. I’m convinced this is because they don’t REALLY want you to maximise your saving.

    It would be great to poke them in the eye and come up with something that did the job another way,

    12 May 2018 at 20:15

    Reply
32. 

    Sian says:

    That’s a great app! I’ve been working on a way to get csv of target and actual temperatures. It looks like that was your intention too, but I only see one line on the graph, for Temperature, and nothing for Target. Are you still developing it? I’ve got to the point where I can now run an on demand NodeRED job on my raspberry pi, which emails Temperature and Target readings for a specified time period, as json, to me, but I still have to do a lot of manual processing to turn this into a graph.

    13 May 2018 at 08:46

    Reply
    • 

      Paul Bloomfield says:

      Hi, sorry for the delay. The target is displayed as well as actual, it is displayed as an area chart in a lighter red.

      30 May 2018 at 19:03

      Reply
    • 

      Paul Bloomfield says:

      Oh and thanks for the compliment, yes I was planning to do some more work on the app, including publishing the (nodejs) back end.

      30 May 2018 at 19:11

      Reply
33. 

    Andrew Young says:

    Great API guide thanks. Hope you don’t mind me plugging this, but I’ve produced a hive web server app in Node.Js I plan on enhancing. Currently it allows you to view the JSON output from the APIs and export the history to a .csv format (one thing I noticed from the API is that if you request the temperature and target temperature, there might be gaps in the date/times requested in one or the other which makes it hard to compare. My export function will fill in the gaps to make sure you can import and graph both side by side without risk of them getting out of step).

    The app is on github here: https://github.com/ajyounguk/hive-client

    25 May 2018 at 18:27

    Reply
    • 

      Rich says:

      Hi Andrew I am trying to really hard to get your app working from GITHUB that you link to here, however I keep getting the follwing error, any ideas how to fix?
      Error: Cannot find module ‘json file’
      at Function.Module._resolveFilename (internal/modules/cjs/loader.js:581:15)
      at Function.Module._load (internal/modules/cjs/loader.js:507:25)
      at Module.require (internal/modules/cjs/loader.js:637:17)
      at require (internal/modules/cjs/helpers.js:22:18)
      at new View (C:\HIVE\hive-client-master\node_modules\express\lib\view.js:81:14)
      at Function.render (C:\HIVE\hive-client-master\node_modules\express\lib\application.js:570:12)
      at ServerResponse.render (C:\HIVE\hive-client-master\node_modules\express\lib\response.js:1008:7)
      at C:\HIVE\hive-client-master\controllers\hiveController.js:180:25
      at Layer.handle [as handle_request] (C:\HIVE\hive-client-master\node_modules\express\lib\router\layer.js:95:5)
      at next (C:\HIVE\hive-client-master\node_modules\express\lib\router\route.js:137:13)

      12 December 2018 at 16:49

      Reply
      • 

        Andrew Young says:

        Hi Rich – sorry – not been monitoring things here at all, best way to get in touch is to create an issue on the git repository. Having said I’ve recreated your error, it can’t open the hive.config.json file with your hive user/password. Check the config directory, you need to copy the config-sample.json file to config.json and edit it with your credentials. There are instructions in the git readme to do this too. I’ll change the code to make the error for this condition a bit more user friendly.

        18 January 2019 at 09:35

        Reply
      • 

        Andrew Young says:

        Hi Richard – FYI this has been fixed on the github repo

        16 May 2019 at 13:51

        Reply
34. 

    Chris says:

    Can this be used to detect whether or not a door/window sensor is open/closed.

    I ask as I want to write something that will alert me to any open windows in my office at 5pm, so no windows are left open overnight.

    Eg, if time is >5pm and sensor=open then email/text me

    Hive do not have a recipe for this and I cannot think of a way to do it with IFTTT so my only recourse is a possible api solution.

    Any ideas?

    7 August 2018 at 10:33

    Reply
35. 

    Andy Jacobs says:

    Well, the learning curve has been steep as I started my little project with no knowledge of how to use an API and no programming experience apart from a bit of PHP. This guide has been invaluable. I’ve now go a Raspberry Pi sniffing for the Bluetooth MAC addresses of everyone in the house and writing the status to a MySQL database. This is done with a Python Flask route that gets run every 5 minutes via a cron job. Another route then checks to see who’s in and sets the heating accordingly. I’ve also written a little app to turn on/off the occupancy based stuff, adjust the temperature and turn the boost on and off with a nicer dashboard.

    This all works a treat so I now have proper occupancy based control to turn the heating off if the house is empty.

    I’m just wondering 3 things…

    – If Hive will ever support the API properly
    – Whether there is any limit on API calls per user
    – Whether they might just shut the API down at any time

    6 November 2018 at 09:39

    Reply
36. 

    Damien Z says:

    I’ve created some software that uses the Hive API to give much more controlover the Hive system and schedules. It was aimed at landlords but it also logs all of the temperature data to Excel for analysis so may be of some use to all sorts of people https://quantum-key.net/AppPages/204-British-Gas-Hive-Landlord-Control.htm

    19 November 2018 at 21:47

    Reply
37. 

    L.Mario says:

    Hi, where can I find official documentation?
    Where can I get the APi-Key to implement the APIs?

    29 November 2018 at 11:15

    Reply
38. 

    Max London says:

    Is there a Python API?

    8 December 2018 at 16:49

    Reply
39. 

    Mitul says:

    Does “THERMOSTAT SET” API support decimal values for “targetValue”?
    Example:

    {
    “nodes”: [{
    “attributes”: {
    “targetHeatTemperature”: {
    “targetValue”: 22.5
    }
    }
    }]
    }

    20 December 2018 at 20:53

    Reply
40. 

    Steve says:

    Hi not sure if this thread is still active. i am tying to following the tutorials here, but when I type ./hiveToOpenHAB.sh -getIDs all I get is ERROR: Empty data
    Any ideas, thanks in advance Steve

    7 January 2019 at 22:07

    Reply
41. 

    Steve says:

    I am actually getting a little further now, but am tottaly stuck on this error

    Curl_http_done: called premature == 0
    100 130 0 42 100 88 144 302 –:–:– –:–:– –:–:– 303
    * Connection #0 to host api-prod.bgchprod.info left intact
    Session: { “error”: { “reason”: “Could not read json” } }
    jq: error (at :1): Cannot iterate over null (null)
    SessionID:
    % Total % Received % Xferd Average Speed Time Time Time Current
    Dload Upload Total Spent Left Speed
    100 38 100 38 0 0 161 0 –:–:– –:–:– –:–:– 162

    7 January 2019 at 23:17

    Reply
42. 

    Luke says:

    I’m late to the game on this, but have been trying to get a session ID and it looks like I’ve got something wrong, or the API has changed. When trying to get the session ID, the response is:
    “code”: “USERNAME_PASSWORD_ERROR”,
    “title”: “Username or password not specified or invalid”

    I’ve verified I can log in with my creds, I even downloaded the landlord app above to test and it cannot get a session ID, which tells me something changed.

    Any ideas?

    24 January 2019 at 22:42

    Reply
    • 

      Derek S says:

      Luke, did you solve your issue. I’ve just spotted that my Python program that hase been happily logging data from Hive is now having to logon every time. I’m guessing something has changed about the use of Session IDs.
      Thanks
      Derek

      27 March 2019 at 00:09

      Reply
    • 

      Daniel says:

      I’m in the same boat as Luke here, getting this same error, anyone know if the API has changed?

      10 September 2019 at 08:40

      Reply
43. 

    Thomas says:

    auth/session works fine for me. But when I use /nodes I get the following error. Anyone know what it means?

    {
    “errors”: [
    {
    “code”: “SERVICE_UNAVAILABLE”,
    “title”: “Service unavailable”,
    “detail”: “Hystrix circuit short-circuited and is OPEN”,
    “links”: []
    }
    ]
    }

    2 April 2019 at 14:30

    Reply
    • 

      Thomas says:

      Ah, Hive is down currently: https://status.hivehome.com/?_ga=2.190831203.953042227.1554188907-653889615.1554188907

      2 April 2019 at 14:50

      Reply
44. 

    Ian Cox says:

    Working perfectly, developing my own control/info panel solution for the heating so far but intend to extend the system to the other hive controlled products in the future. This was just the head start I needed.

    Only issue I really have is the ‘attributes’ values. Obviously a dictionary of mixed object types, using C# JsonConvert (NewtonSoft) I have yet to find a way to define object maps for the JSON. Is there anyway of getting to the schemas defined in the ‘NodeType’ fields. Tried my usual approaches but came up lacking.

    Next step to look at channels and historical data for temperature and heating on/off events.

    10 April 2019 at 09:09

    Reply
45. 

    Alan says:

    I can get Boost working with “activeHeatCoolMode”: {“targetValue”: “BOOST”} as in the example, and I can switch off the thermostat by setting targetValue to OFF, but I can’t seem to get the thermostat to switch back on, either to SCHEDULE or MANUAL. Does anyone have the json to accomplish this?

    14 September 2019 at 20:55

    Reply
    • 

      Thomas says:

      Try this, replacing target value with the temp you want it to go to. I’m not sure if it’ll work

      {
      attributes: {
      targetHeatTemperature: {
      targetValue: 21.0
      },
      activeScheduleLock: {
      targetValue: true
      },
      scheduleLockDuration: {
      targetValue: 0
      },
      activeHeatCoolMode: {
      targetValue: “HEAT”
      }
      }
      }

      17 January 2020 at 17:37

      Reply
      • 

        Alan Carter says:

        Thanks Thomas, I figured out the solution a few days after I posted the question and should have posted the answer! You’re right, but the duration isn’t required. Set the lock to True for Manual, False for Schedule.

        17 January 2020 at 19:06

        Reply
46. 

    Bruce says:

    This all looks great. Have managed to get live temps from all TRVs using “node” and get the history for one or more valves using “channels” which is all good stuff. Is there a way of being able to see if a valve is open or closed from the API ?

    4 November 2019 at 16:27

    Reply
47. 

    Chris says:

    Any idea how to get oauth2 to work with this? I don’t like having to store my username and password. I can get a bearer token using the Swagger interface, and I can use it for requests using
    “Authorization: Bearer $TOKEN”
    but I can’t find out how to refresh it

    https://oauth.prod.bgchprod.info/oauth2/token
    seems to want to play ball, but I even with my username and password, it always returns Unauthorised

    21 July 2020 at 00:15

    Reply
48. 

    Chris says:

    It seems like this API has been blocked now. It’s been working fine for me for a couple of years, but now when I try to get a session from
    https://api.prod.bgchprod.info/omnia/auth/sessions
    I get the response:

    {
    “genericError”: {
    “error”: {
    “reason”: “GONE”,
    “message”: “Not supported anymore”
    }
    }
    }

    This happens both with curl calls and with the Swagger UI

    2 October 2020 at 16:20

    Reply
    • 

      BobnMax says:

      some discussion around the topic here.
      https://community.home-assistant.io/t/hive-integration/17374/607

      2 October 2020 at 17:21

      Reply
    • 

      Rick says:

      Same here – I noticed my cron job hadnt been able to call the api since 2pm yesterday….

      3 October 2020 at 07:59

      Reply
    • 

      Chris B says:

      Me too!
      2 years hard work setting up switches & TRV’s suddendly stopped the same day I was fitting an extra 5 TRV’s

      5 October 2020 at 20:43

      Reply
      • 

        Rick says:

        I changed my code to get the sessionid using the following

        sessionId=$(curl -H “Host: beekeeper.hivehome.com” -H “Content-Type: application/json” -H “Accept: /” -H “User-Agent: HiveRNApp/10.16.2 Mozilla/5.0 (iPhone; CPU iPhone OS 13_1_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148” -H “Accept-Language: en-gb” –data-binary ‘{“username”:”YOURUSERNAME”,”password”:”YOURPASSWORD”,”devices”:true,”products”:true,”actions”:true,”homes”:true}’ –compressed ‘https://beekeeper.hivehome.com/1.0/cognito/login’ | python -c “import sys,json; print json.load(sys.stdin)[‘token’]”)

        7 October 2020 at 08:08

        Reply
    • 

      Chris B says:

      Excellent result !
      I have just today got it working almost perfectly after using the following very similar code to above in the original script:-
      session=$(curl -s -k -g -H “Content-Type: application/json” \
      -H “Accept: application/json” \
      -d ‘{“username”:”xxxxxx@icloud.com”,”password”:”xxxxxx”}’ \
      https://beekeeper.hivehome.com/1.0/cognito/login)
      sessionId=$(echo $session | python -c ‘import sys, json; print json.load(sys.stdin)[“token”]’)

      10 October 2020 at 13:32

      Reply
49. 

    Rick says:

    Has the access to hive api gone again. I’m getting a “forbidden” error when trying to request the session id.

    18 December 2020 at 09:40

    Reply