Hive REST API v5

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.

When will Hive release their API?
Hive Honeycomb API

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?

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:

  1. 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.
  2. 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.

12 Comments

Add a Comment

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