Mar
For anyone looking for the newer v6 API see here.
Documentation of an API for the Hive platform is somewhat elusive, but this is not because of lack of demand… There are countless forum, social media and support requests begging Hive to release an API and IFTTT support, which would then empower developers to create innovative new applications as well integration with other home automation platforms such as SmartThings and Vera. Without such an API Hive will always be shadowed by the likes of Nest and Philips Hue.
There have been a few announcements from Hive about a new development platform called ‘Honeycomb’ but no firm dates and, much like IFTTT support, the promise has been like a carrot on a stick and of late has gone a little quiet.
AlertMe API v5
Luckily documentation for Hives predecessor from AlertMe is a little more available, and fortunately Hive inherits much of the same API. The following are a few examples from the AlertMe API which also work for Hive:
The API is a RESTful service. All returned data is JSON encoded. There are two API URLs used by British Gas Hive systems, I am not sure which is the most appropriate to use but they both appear to work:
- https://api.bgchlivehome.co.uk/v5
- https://api.prod.bgchprod.info/api
For completeness the following two URLs were used by AlertMe and Lowes Iris systems, these will not work for Hive:
- https://api.alertme.com/v5
- https://api.irissmarthome.com/v5
Login
[POST] /login
Arguments:
- username : Hive username (for Hive this is your email address)
- password : Hive password
- caller : Caller of the API (e.g WEB, iPhone, Android)
Before any other calls can be made you must login. This will return a WebApiSession cookie which must then be sent with all consequent calls. Session will expire after 20 idle minutes.
After successful login the API will also return the hub ID associated with your user – take note of this ID, it will be used in a number of the other consequent calls.
Example Response:
{
"hubIds": [
"1234567890987654321"
],
"userId": 1234567,
"partnerId": 1,
"username": "user@domain.co.uk",
"tandcConfirmed": true,
"extCustomerLevel": 1,
"permissions": [],
"ApiSession": "c7f801cf07de6a6f3312efa13d39e71d"
}
Logout
[POST] /logout
Ends the session, after which the session cookie will no longer be valid.
This call returns no JSON but response HTTP Code 204 = Success.
Hub Details
[GET] /users/:username/hubs/:hubId
Returns details of hub including hub ID, name, MAC address, firmware version and uptime. Where :username is your Hive username and :hubId is your hub ID as returned from the login call above.
Example Response:
{
"available": true,
"configured": true,
"version": "1.0.0-4563-0.0",
"latestVersion": "1.0.0-4563-0.0",
"upgrade": "INELIGIBLE",
"reason": "ALREADY_AT_LATEST_VERSION",
"powerType": "AC",
"connectionType": "BROADBAND",
"connection": "ETHERNET",
"onSince": 0,
"upTime": 300632,
"uptime": 300632,
"timezone": 0,
"daylightSaving": "EU",
"behaviourId": 1,
"behaviourType": "HOME",
"model": "NANO2",
"ip": "192.168.0.106",
"externalIp": "n/a",
"hardwareRevision": 1,
"zigbeeNetworkInfo": 22,
"macAddress": "ABC-123 (00:1C:2B:09:90:12)",
"name": "Hub",
"upgrading": false,
"bootLoaderVersion": "2013.04-g60890ce",
"zigBeeTileFirmwareVersion": "R311 B051015",
"kernelVersion": "3.12.10",
"rootFSVersion": "The Ångström Distribution",
"status": 99
}
Device List
[GET] /users/:username/hubs/:hubId/devices
Returns a list of devices associated with the hub. Note username and hubId. You may see listed devices such as HAHVACTemperatureSensorSLT3 (Thermostat), HAHVACThermostat (Receiver), GenericRangeExtender (Signal Booster) and SmartPlugs.
Example Response:
[
{
"id": "::21e:5e09:20f:5ac3",
"name": "Your Thermostat",
"type": "HAHVACTemperatureSensorSLT3",
"nodeType": "http://alertme.com/schema/json/node.class.thermostatui.json#",
"channels": {
"presence": true,
"tamper": false,
"temperature": null,
"battery": 5.5,
"batteryPercentage": 60,
"batteryLevel": 3,
"signal": 100
}
},
{
"id": "::20d:6f00:3bb:b9f8",
"name": "Signal Booster",
"type": "SmartPlug",
"nodeType": "http://alertme.com/schema/json/node.class.smartplug.json#",
"channels": {
"presence": true,
"tamper": false,
"temperature": null,
"battery": null,
"batteryPercentage": null,
"batteryLevel": null,
"signal": 100
}
}
]
Temperature Get
[GET] /users/:username/widgets/temperature
Returns the current temperature of the house and outside weather condition. All temperatures are provided in degrees Celsius or Fahrenheit according to the ‘temperatureUnit’ parameter.
Example Response:
{
"temperatureUnit": "C",
"inside": {
"now": 21.1,
"averages": {
"today": 0,
"yesterday": 0,
"lastWeek": 0
}
},
"outside": {
"now": 7,
"weather": {
"now": "day_black_low_cloud",
"description": "Partly Cloudy "
}
}
}
Temperature History
[GET] /users/:username/widgets/temperature/:deviceId/history
Arguments:
- period : e.g ‘today’
- year : e.g ‘2016’
- month : e.g ’03’
Get temperature history. Note deviceId is the MAC address ID of your thermostat and should be URL encoded e.g ‘%3A%3A21e%3A5e09%3A20d%3A8ed’.
Example Response:
{
"period": "today",
"temperatureUnit": "C",
"data": [
{
"date": "2016-03-15 00:00",
"temperature": 19.18
},
{
"date": "2016-03-15 00:30",
"temperature": 19.03
}
]
}
Temperature Set
[POST] /users/:username/widgets/climate/targetTemperature
Arguments:
- temperature : e.g ’19’
- temperatureUnit : e.g ‘C’
This call returns no JSON but response HTTP Code 204 = Success.
Topology
[GET] /users/:username/hubs/:hubId/topology
Topology of Zigbee network.
Example Response:
[
{
"id": "00-00-00-00-00-00-00-00",
"children": [
{
"id": "::21e:5e09:20f:5ac3"
},
{
"id": "::20d:6f00:3bb:b9f8"
},
{
"id": "::21e:5e09:211:943d"
},
{
"id": "::21e:5e09:20d:8ed"
}
]
}
]
Nodes
[GET] /users/:username/nodes
List of devices.
Example Response:
{
"links": [
{
"rel": "self",
"href": "/users/user@domain.co.uk/nodes"
},
{
"rel": "child",
"href": "/users/user@domain.co.uk/nodes/::20d:6f00:3bb:b9f8@2029726571442470913"
},
{
"rel": "child",
"href": "/users/user@domain.co.uk/nodes/::21e:5e09:20d:8ed@2029726571442470913"
}
],
"content": [
"::20d:6f00:3bb:b9f8@2029726571442470913",
"::21e:5e09:20d:8ed@2029726571442470913"
]
}
Events
[GET] /users/:username/events
Arguments:
- limit : e.g ‘100’
List of events on the Hive system, hub status, new devices, associations.
Example Response:
{
"events": [
{
"id": "8f4c9000-e82d-11e5-ae1b-0afc8eae08e7",
"type": "PRESENT",
"source": "::21e:5e09:211:943d",
"nodeName": "Signal Booster",
"parent": null,
"time": "2016-03-12T08:36:48.000+0000",
"properties": null
},
{
"id": "8194b450-ac47-11e5-9c7b-062f4d93a695",
"type": "REJOINED",
"source": "::21e:5e09:20f:5ac3",
"nodeName": "Your Thermostat",
"parent": null,
"time": "2015-12-27T03:11:22.133+0000",
"properties": {
"deviceType": "THERMOSTAT_UI"
}
}
]
}
SmartPlug On/Off Status
[GET] /users/:username/widgets/smartplugs/:deviceId/onOffState
[PUT] /users/:username/widgets/smartplugs/:deviceId/onOffState
Arguments:
- onOffState : ‘on’ or ‘off’
Get and set SmartPlug on/off status. Note deviceId is the MAC address ID of your SmartPlug and should be URL encoded e.g ‘%3A%3A20d%3A6f00%3A3bb%3Ab9f8’.
Example Response:
{
"error": {
"reason": "Unexpected error occurred, please try again later"
}
}
As you can see the response is an “Unexpected error occurred”, which is different from other error messages where the call is completely wrong, which leads me to believe there is still something there for the smartplug call.
{
"error": {
"reason": "NON_EXISTENT_CALL_OR_INVALID_VARIABLES_WITHIN_URI"
}
}
Still this API call particularly interests me, as when the SmartPlug was used in an AlertMe system the above call could be used to remotely switch the plug on and off as well as read power usage values. However when in a Hive system the only “smart” thing the plug does is act as a signal booster and can not be switches of and off over Zigbee. I have written about this in a previous post as I am sure that, if Hive wanted to, these plugs could be re-enabled for remote control (please see voting link below).
API Documentation
These took a little bit of hunting but the following is the documentation for the AlertMe API’s V2.2, V5 and V6.1 (I am not really sure if v6.4 is going to be ‘Honeycomb’ or whether is an older API from AlertMe which is to be retired?
- AlertMe API v2.2 Documentation [source]
- AlertMe API v5.0 Documentation [source]
- AlertMe API v6.1 Documentation [source]
Please Vote
If you found this post useful, please could I ask a favour in return? Please can you vote on 2 Hive product requests on the Hive customer feedback site:
- Make the SmartPlug ‘smart’ again – This is more of a personal product request for which I am asking Hive to enable their older ‘SmartPlug’ for remote control.
- Hive API Request – On topic for this post, this is a product request for Hive to provide a published API which could also be used by IFTTT etc.
Voting is extremely easy and I hope that with enough demand may persuade Hive take notice.
smartofthehome interesting, cheers
It would be good if someone could write a programme for PC or even RaspberyPi which will present its self to Hive as a number of devices e.gfour remote plugs and three lights. the Pi could then control diferent things.
Nice article, but it seems that in less than a week since this was posted BG have closed down access!
https://api.bgchlivehome.co.uk/v5 now responds ‘no mapping for /v5’ and the other URL simply comes back with ‘unauthorised’ despite trying 2 different logins that both work fine on hivehome.com
It really does seem that BG are determined to keep Hive a ‘closed’ system 🙁
Hi Chris, So sorry for the delayed response (I have just found your comment in my ‘pending approval’ pile in wordpress… sorry…
I have just tested and https://api.bgchlivehome.co.uk/v5 still seems to work fine. Simply visiting this URL is a browser will result in ‘no mapping for /v5’ but if you pass post parameters username, password and caller it should respond with successful login:
{
“hubIds”: [
“xxxxxxxxxxx”
],
“userId”: xxxxxxxxxx,
“partnerId”: 1,
“username”: “xxxxx@xxxxxxxx.net”,
“tandcConfirmed”: true,
“extCustomerLevel”: 1,
“permissions”: [],
“ApiSession”: “xxxxxxxxxxxxx”
}
Through exploring this API, I’ve found that the window/door sensors and the motion sensors have temperature sensors embedded which you can get the data from:
{
“channels”: {
“battery”: 3.0,
“batteryLevel”: 5,
“batteryPercentage”: 100,
“presence”: true,
“signal”: 100,
“tamper”: false,
“temperature”: 18.5
},
“id”: “::d:6f00:5a5:3e9d”,
“name”: “Back Door”,
“nodeType”: “http://alertme.com/schema/json/node.class.contact.sensor.json#”,
“type”: “ContactSensor”
},
{
“channels”: {
“battery”: 3.1,
“batteryLevel”: 5,
“batteryPercentage”: 100,
“presence”: true,
“signal”: 100,
“tamper”: false,
“temperature”: 9.25
},
“id”: “::d:6f00:5a5:53ef”,
“name”: “Old Shed”,
“nodeType”: “http://alertme.com/schema/json/node.class.motion.sensor.json#”,
“type”: “MotionSensor”
},
{
“channels”: {
“battery”: 6.0,
“batteryLevel”: 5,
“batteryPercentage”: 100,
“presence”: true,
“signal”: 100,
“tamper”: false,
“temperature”: null
},
“id”: “::1e:5e09:20f:5b35”,
“name”: “Main Thermostat”,
“nodeType”: “http://alertme.com/schema/json/node.class.thermostatui.json#”,
“type”: “HAHVACTemperatureSensorSLT3”
},
{
“channels”: {
“battery”: 3.1,
“batteryLevel”: 5,
“batteryPercentage”: 100,
“presence”: true,
“signal”: 100,
“tamper”: false,
“temperature”: 9.75
},
“id”: “::d:6f00:5a5:580a”,
“name”: “New Shed”,
“nodeType”: “http://alertme.com/schema/json/node.class.motion.sensor.json#”,
“type”: “MotionSensor”
},
Thanks Simon, this is very useful. Interesting they have temperature sensors in them also, this could be useful.
I hope to write up a similar article to this on the v6 API soon.
Hi James.
Firstly, thanks for your work on the Hive API, it has saved me a lot of head-scratching.
I’ve recently installed a Hive system in my house and would like to get it talking to my Node Red server which is currently doing home automation type stuff. I’m using the code from here: https://github.com/aklambeth/bg-hive-api to achieve this.
Here’s what I get back from a /devices call. Any idea what the GenericUnknown device is?
Also, the current temperature only seems to be available at the receiver and not at the thermostat. The receiver is not where I want to monitor temperature (next to the boiler), or is this nothing to worry about?
Thanks
[
{
“id”: “”,
“name”: “Receiver”,
“type”: “HAHVACThermostatSLR2”,
“nodeType”: “http://alertme.com/schema/json/node.class.thermostat.json#”,
“channels”: {
“presence”: true,
“tamper”: false,
“temperature”: 19.0,
“battery”: null,
“batteryPercentage”: null,
“batteryLevel”: null,
“signal”: 100
},
“maxNumSetpoints”: 6
},
{
“id”: “”,
“name”: “http://alertme.com/schema/json/node.class.synthetic.zonename.initializer.json#”,
“type”: “GenericUnknown”,
“nodeType”: “http://alertme.com/schema/json/node.class.synthetic.zonename.initializer.json#”,
“channels”: {
“presence”: true,
“tamper”: false,
“temperature”: null,
“battery”: null,
“batteryPercentage”: null,
“batteryLevel”: null,
“signal”: null
}
},
{
“id”: “”,
“name”: “Thermostat”,
“type”: “HAHVACTemperatureSensorSLT3”,
“nodeType”: “http://alertme.com/schema/json/node.class.thermostatui.json#”,
“channels”: {
“presence”: true,
“tamper”: false,
“temperature”: null,
“battery”: 6.0,
“batteryPercentage”: 100,
“batteryLevel”: 5,
“signal”: 100
}
}
]
Hi Fergal, So sorry for the delayed response (I have just found your comment in my ‘pending approval’ pile in wordpress… sorry…
I don’t know if you got the answer you were looking for now, but I don’t think it matters that the temperature is being reported by the receiver. It also confused me for a while until I started to think of of the thermostat more as an extension to the receiver. I think the receiver is where all the intelligence is done, schedules are stores etc. where as the thermostat is more of a mobile user interface and remote sensor reporting back (so you could take the batteries out the thermostat and things will continue to work and you could control it from the web app.. except it would not know the current temperature of course!). I don’t think the receiver has a temperature sensor in it.
Looks like they have discontinued the v5 api. There is a problem with the ssl on the v6 too so all the code I previously wrote is now broken on british gas’s whim. Yay
Hi
Chris – did you get this working at all? I’ve tried the API’s and like you I found the same issue. Has anyone else found if there is a V6 API that actually works?
I’ve written a few basic scripts myself based on the work of others. I’ll see if I can get a git repository together tomorrow to share my work.
Hi @chris, @guy,
I just has a quick check and it looks like API v5 is still alive and well.
Also there is a new URL for v6 which does not have SSL error:
https://api-prod.bgchprod.info:443/omnia (no SSL errors)
Replaces:
https://api.prod.bgchprod.info:443/omnia (has SSL errors)
Also, I don’t know if you have seen my other post on v6.1:
http://www.smartofthehome.com/2016/05/hive-rest-api-v6/
Hi, I have a V5 Hive and need help with it. Batteries for it ran out, now it just keeps saying ‘rejoin’… what to do?!
Hive Nano2 as RFLink
I’ve been wondering if it’s possible to reflash a hive nano2 hub with other firmware to create a 2nd “open” zigbee hub? I have 2 hive hubs, one for my hive hardware and a spare. I could sell the spare but so many people are doing the same, so no market for it. Would be a shame to throw it away.
Interesting idea, the Nano hub runs Linux so theoretically possible. I have no idea how you would do it. You may be interested in project https://github.com/jamesleesaunders/PyAlertMe which attempts to recreate a AlertMe/Hive Hub with Pi and Python.