Energyhive API

Show All | Hide All

Data API

API calls for retrieving energy data, the majority of calls for a specified HID

If you have a valid api token instead of an appID you should can use these calls in the form:
http://www.energyhive.com/mobile_proxy/API_CALL_NAME?token=MY_TOKEN¶m1=PARAM1&...
You do NOT need the timestamp, secretkey, appID or HID in this case but any other parameter should be appended.

createHidSimpleTariff (active)

URL:
/api/createHidSimpleTariff.php
Synopsis:
Combined Create and Apply tariff. Only requires a pence per kWh value
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (numeric)cost_per_kwh
Call:
{"securitykey": "HASH_GOES_HERE",
"timestamp": CURRENT_UTC_TIMESTAMP,
"householderID":"YOUR_HID",
"appID": "YOUR_APPID",
"cost_per_kwh" : 11.31 }}
Response:
TBD
Notes:
More complex tariff models are available but not exposed yet.
State:
Active

getBudget (active)

URL:
/api/getBudget.php
Synopsis:
Gets a value for the monthly budget for a HID
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID
Call:
{"appID":"YOUR APPID",
"securitykey":"HID HASH",
"timestamp":'CURRENT TIMESTAMP',
"householderID":"HID"}
Response:
{'status':'ok', 'monthly_budget':20.12}
Notes:
The budget value should be in pounds and pence ( or just pounds ).
The budget can be set using the setBudget Call.
State:
Active

getCarbon (active)

URL:
/api/getCarbon.php
Synopsis:
Gets the amount of carbon generated by the energy production to meet the usage of the household over a given period. By default the usage so far "this month" is returned.
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(period) period], [(ts) fromTime, (ts) toTime]
Returns:
A JSON object with a value, the units that apply to the value and the length of the period in question in seconds.
Call:
{"securitykey":"HID HASH",
"timestamp":"UTC TIME",
"householderID":"Your HID",
"appID": "APP ID",
"offset" : -60,
"period" : "custom",
"fromTime" : "1325379600",
"toTime" : "1337599746" }
Response:
{"sum":"70.57","duration":12220146,"units":"kg co2"}
Notes:
Available periods are: 'day','week','month','year' and 'custom'. This is optional and if not provided defaults to month. This will, in effect, give you the amount so far in this calendar period e.g. 1st of month until now.
If 'custom' is specified the fromTime and toTime must be supplied. These must be supplied as seconds since the unix epoch in localtime ( NOT UTC ).
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
fromTime must be in the past and toTime must occur after fromTime.
If the type is 'day', 'week', 'month' or 'year' the optional time parameters are ignored and the cost for the current time period is returned.
State:
Active

getChannelAggregated (active)

URL:
/api/getChannelAggregated.php
Synopsis:
Returns a timeseries of aggregated devices on a given channel for a hid
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, (ts) fromTime, (ts) toTime, aggPeriod, [(aggFunc)aggFunc] (string)type (numeric)carbonRatio (int)cacheTTL, (int)cacheKey
Returns:
An array containing object containing consumed/cost/co2 with a timestamp as a key.
Notes:
I Assume this is an aggregate of the PWER channels. cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getCompCombined (active)

URL:
/api/getCompCombined.php
Synopsis:
Retrieves the comparison data between a given household and all other households for day, week and month. The comparisons are also available elsewhere separately ( getCompDay etc. )
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, [(int) offset]
Returns:
A comparison object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"day":{"avg":{"sum":"1327.81"},"avgAttr":{"sum":"1964.27"},"hid":{"sum":"2246.50"}},
"week":{"avg":{"sum":"6737.73"},"avgAttr":{"sum":"9656.56"},"hid":{"sum":"10045.08"}},
"month":{"avg":{"sum":"28650.90"},"avgAttr":{"sum":"29427.00"},"hid":{"sum":"54028.14"}}}
Notes:
Only Comparisons against ALL other households are currently supported. More comparison options e.g. compare against same number of bedrooms etc. coming soon.
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60. If no offset is provided the current UK time is assumed.
The values returned reflect the consumption in the preceding timespan, not a calendar period. E.g. week would be the consumption from (now - 1 week) until (now).
As months vary they are assumed to be 28 days (4 weeks).
For historical reasons the values are in kWm
If the user has less than 7 days history only the day comparison will return, if less than 28 days the month comparison will not show.
If less than 1 days data then the return will just consist of status=ok, description=not enough data
State:
Active

getCompDay (active)

URL:
/api/getCompDay.php
Synopsis:
Retrieves the comparison data between a given household and all other households over the period of a day.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset
Returns:
A comparison object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"day":{"avg":{"sum":"12.55"},"avgAttr":{"sum":"19.86"},"hid":{"sum":"22.88"}}}
Notes:
Only Comparisons against ALL other households are currently supported.
More comparison options e.g. compare against same number of bedrooms etc. coming soon.
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
Units returned are kWh.
This is a wrapper of the getComp call.
State:
Active

getCompMonth (active)

URL:
/api/getCompMonth.php
Synopsis:
Retrieves the comparison data between a given household and all other households over the period of a month.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset
Returns:
A comparison object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"day":{"avg":{"sum":"12.55"},"avgAttr":{"sum":"19.86"},"hid":{"sum":"22.88"}}}
Notes:
Only Comparisons against ALL other households are currently supported.
More comparison options e.g. compare against same number of bedrooms etc. coming soon.
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
Units returned are kWh.
This is a wrapper of the getComp call.
Note that a 'month' is actually 28 days, for a full calendar month use the getComp call with custom from and to times.
State:
Active

getCompWeek (active)

URL:
/api/getCompWeek.php
Synopsis:
Retrieves the comparison data between a given household and all other households over the period of a week.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset
Returns:
A comparison object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"day":{"avg":{"sum":"12.55"},"avgAttr":{"sum":"19.86"},"hid":{"sum":"22.88"}}}
Notes:
Only Comparisons against ALL other households are currently supported.
More comparison options e.g. compare against same number of bedrooms etc. coming soon.
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
Units returned are kWh.
This is a wrapper of the getComp call.
State:
Active

getCompYear (active)

URL:
/api/getCompYear.php
Synopsis:
Retrieves the comparison data between a given household and all other households over the period of a year.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset
Returns:
A comparison object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"day":{"avg":{"sum":"12.55"},"avgAttr":{"sum":"19.86"},"hid":{"sum":"22.88"}}}
Notes:
Only Comparisons against ALL other households are currently supported.
More comparison options e.g. compare against same number of bedrooms etc. coming soon.
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
Units returned are kWh.
This is a wrapper of the getComp call.
State:
Active

getConsumptionCostCO2Graph (active)

URL:
/api/getConsumptionCostCO2Graph.php
Synopsis:
Returns a timeseries of consumed/cost and c02
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(ts) fromTime, (ts) toTime, aggPeriod, (numeric)carbonRatio (int)cacheTTL, (int)cacheKey
Returns:
An array containing object containing consumed/cost/co2 with a timestamp as a key.
Notes:
Aggregate of the PWER channels. cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getConsumptionGeneratedAndImport (active)

URL:
/api/getConsumptionGeneratedAndImport.php
Synopsis:
Only useful if PWER and PWER_GAC channels are present. Delivers the proportion of consumed power that is generated in the home vs that imported
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, (ts) fromTime, (ts) toTime, (int)cacheTTL, (int)cacheKey
Returns:
A object containing the total consumed, the amount generated in home and the amount imported ( see example below ) or JSON error message.
Response:
{"consumption":"55480.00","generated":"36007.00","imported":"19473.00"}
Notes:
cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getCost (active)

URL:
/api/getCost.php
Synopsis:
Gets the cost for energy consumption with the tariff that has been set for the household. By default the usage so far this month is returned.
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(period) period], [(ts) fromTime, (ts) toTime]
Returns:
A JSON object with a value for consumption, the units that apply to the value and the length of the period in question in seconds.
Call:
{"securitykey":"HID HASH",
"timestamp":"UTC TIME",
"householderID":"Your HID",
"appID": "APP ID",
"offset" : -60,
"period" : "custom",
"fromTime" : "1325379600",
"toTime" : "1337599746" }
Response:
{"sum":"70.57","duration":12220146,"units":"GBP"}
Notes:
Available periods are: 'day','week','month','year' and 'custom'. This is optional and if not provided defaults to month. This will, in effect, give you the amount so far in this calendar period e.g. 1st of month until now.
If 'custom' is specified the fromTime and toTime must be supplied. These must be supplied as seconds since the unix epoch in localtime ( NOT UTC ).
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
fromTime must be in the past and toTime must occur after fromTime.
If the type is 'day', 'week', 'month' or 'year' the optional time parameters are ignored and the cost for the current time period is returned.
Note that the tariff must have been set for this HID, if not an error will be returned.
State:
Active

getCountryList (active)

getCurrentValuesSummary (active)

getDay (active)

URL:
/api/getDay.php
Synopsis:
Retrieves the historical timeseries of consumption data for a household for the previous 24 hours. Data will be returned at a minute level of resolution.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset, [(int) getPreviousPeriod], [(bool) cache]
Returns:
JSON object OR error. The json object consists of a list of timestamps (milliseconds from epoch), each with an array of consumption values. array[0] is the value for the current period, array[1] is the corresponding value from 24 hours previously. The units are kW.
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT_TS,
"appID":"APPID",
"householderID":"HOUSEHOLD ID"}
Response:
{"status":"ok",
"data":{"1335892740000":[0.18,0.24],
.... ,
"1335979140000":["undef",0.18]}}
Notes:
offset should be the number of minutes away from UTC. e.g. BST (GMT+1) should be -60 )
If getPreviousPeriod is > 0 the previous day's consumption will be returned as well
If data is missing for a given point 'undef' will be returned.
Note that the consumption values in this case are the average kW values for each minute of the day
The timestamps will have been adjusted to your timezone as specified in your offset argument - do not do any more conversion on them
If the offset is not passed the timezone will default to London/Europe.
If you this doesn't meet your requirements please use getTimeSeries which enables you to build a custom query
We cache for a sensible time to improve performance, it is recommended to not switch off the cache.
State:
active

getEnergy (active)

URL:
/api/getEnergy.php
Synopsis:
Gets the amount of energy consumed by a household over a given period. By default the usage so far "this month" is returned.
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(period) period], [(ts) fromTime, (ts) toTime]
Returns:
A JSON object with a value, the units that apply to the value and the length of the period in question in seconds.
Call:
{"securitykey":"HID HASH",
"timestamp":"UTC TIME",
"householderID":"Your HID",
"appID": "APP ID",
"offset" : -60,
"period" : "custom",
"fromTime" : "1325379600",
"toTime" : "1337599746" }
Response:
{"sum":"70.57","duration":12220146,"units":"kWh"}
Notes:
Available periods are: 'day','week','month','year' and 'custom'. This is optional and if not provided defaults to month. This will in effect give you the amount so far in this calendar period e.g. 1st of month until now.
If 'custom' is specified the fromTime and toTime must be supplied. These must be supplied as seconds since the unix epoch in localtime ( NOT UTC ).
The Offset is the number of minutes your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
fromTime must be in the past and toTime must occur after fromTime.
If the type is 'day', 'week', 'month' or 'year' the optional time parameters are ignored and the cost for the current time period is returned.
State:
Active

getEstCombined (active)

URL:
/api/getEstCombined.php
Synopsis:
Retrieves the Estimated usage data for a given household for the current day and current month. The comparisons are also available elsewhere separately ( see getForecast )
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, [(int)numDays]
Returns:
A JSON Estimate object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"day_kwh":{"estimate":34.28,"futureEstimate":17.66, "previousSum":16.62},
"day_tariff":{"estimate":1.86,"futureEstimate":0.96,"previousSum":0.9},
"day_co2":{"estimate":68.54,"futureEstimate":35.31, "previousSum":33.23},
"month_kwh":{"estimate":1150.03,"futureEstimate":1057.84, "previousSum":92.18},
"month_tariff":{"estimate":85.13,"futureEstimate":78.3, "previousSum":6.82},
"month_co2":{"estimate":2299.96,"futureEstimate":2115.6, "previousSum":184.36},
"month_budget":138.875}
Notes:
Note that month_budget is dependant on the optional est_annual_consumption field in the setHousehold call OR the setBudget call.
The optional numDays argument will force check to see if there is enough data to produce accurate estimates.
The default is set to 10 - i.e. the first data entry must be at least 10 days ago. Set to 0 to bypass the check.
State:
Active

getFirstData (active)

URL:
/api/getFirstData.php
Synopsis:
Returns the first data point time. ( UTC )
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID
Returns:
A JSON object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID"}
Response:
{"status":"ok","firstData":"1347987960"}
Notes:
N/A
State:
Active

getForecast (active)

URL:
/api/getForecast.php
Synopsis:
Gets the forecast for energy consumption, greenhouse gas generation or cost ( if tariff set).
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (period) period, (int) offset, [(data_type) dataType]
Returns:
A JSON object comprising of the estimated total usage, estimated future usage and usage so far ( where estimated future and usage so far == estimated total)
Call:
{"appID":"APPID","securitykey":"HID_HASH","timestamp":'UTC TIMESTAMP',"householderID":"HID","period":"month", "offset":-60, "dataType":"cost"}
Response:
{"month_tariff":{"estimate":153.48,"futureEstimate":7.49,"previousSum":145.99},"month_budget":20.12}
Notes:
Available periods are: 'day' and 'month'
Available data type are: 'kwh', 'gas' and 'cost'. The default is kwh.
The Offset is the number of seconds your timezone is off UTC e.g. for BST ( UTC +1) the value passed should be -60.
Note that if the dataType is cost the monthly budget is returned as well.
State:
Active

getGeneratedConsumptionAndExport (active)

URL:
/api/getGeneratedConsumptionAndExport.php
Synopsis:
Only useful if PWER and PWER_GAC channels are present. Delivers the proportion of generated power that is used in the home vs that exported
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(ts) fromTime, (ts) toTime], (int)cacheTTL, (int)cacheKey
Returns:
A object containing the total generated, the amount consumed in home and the amount exported ( see example below ) or JSON error message.
Response:
{"consumedInHome":"36007.00","exported":"12534.00","generated":"48541.00"}
Notes:
cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getGeneratedEnergyRevenueCarbon (active)

URL:
/api/getGeneratedEnergyRevenueCarbon.php
Synopsis:
Returns a timeseries of consumed, revenue and c02 saved
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(ts) fromTime, (ts) toTime, aggPeriod, (numeric)carbonRatio (int)cacheTTL, (int)cacheKey
Returns:
An array containing object containing consumed/cost/co2 with a timestamp as a key.
Notes:
I Assume this is an aggregate of the PWER_GAC channels. cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getGenerationConsumptionGraph (active)

URL:
/api/getGenerationConsumptionGraph.php
Synopsis:
Only useful if PWER and PWER_GAC channels are present. Delivers a timeseries array of consumed/generated/genconsumed/exported/imported
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(ts) fromTime, (ts) toTime, aggPeriod, (int)cacheTTL, (int)cacheKey
Returns:
An array containing object containing consumed/generated/genconsumed/exported/imported with a timestamp as a key.
Response:
[{"1383642000000":[0.01875,0.0125166666666667,0.0125166666666667,0,0.00623333333333333]},
{"1383642300000":[0.01925,0.0124666666666667,0.0124666666666667,0,0.00678333333333333]}]
Notes:
cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getGenerationConsumptionGraphCostRevenue (active)

URL:
/api/getGenerationConsumptionGraphCostRevenue.php
Synopsis:
Only useful if PWER and PWER_GAC channels are present. Delivers a timeseries array of consumed/generated/genconsumed/exported/imported costs/revenue
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(ts) fromTime, (ts) toTime, aggPeriod, (int)cacheTTL, (int)cacheKey
Returns:
An array containing object containing Consumed Network Value,Cost saved,Import cost,Export revenue, Revenue from unconsumed generated energy with a timestamp as a key.
Response:
[
{"1383782400000":["0.00957600","0.00957600","0.00000000","0.01399200"]},
{"1383786000000":["0.00937600","0.00937600","0.00000000","0.01250400"]},
{"1383789600000":["0.00953400","0.00953400","0.00000000","0.01514200”]}
]
Notes:
cacheTTL determine how long the result is cached on the server for in seconds. Recommend a min of 60, rising for longer query periods - hour or potentially day.
cacheKey gives an identifier to aid with caching. As the stamps continually vary they can't be used as a cacheKey this should identify the intention - e.g. last24hr
State:
Active

getHV (active)

URL:
/api/getHV.php
Synopsis:
Returns array of historical values.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int)offset, [(ts) fromTime, (ts) toTime, aggFunc, aggPeriod, type
Returns:
An array containing readings from each sensor that provides the given type of data.
Notes:
type can currrently be PWER, LGHT, MOTN or TEMP.
State:
active

getHousehold (active)

URL:
/api/getHousehold.php
Synopsis:
Gets a household's attributes as set in setHousehold.php
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT TIMESTAMP,
"householderID":"HID",
"appID": "'APPID"
}
Response:
{"ageOfProperty":1,"typeOfProperty":12,"numOfBedrooms":16}
Notes:
Useful mainly for an update household attributes form.
State:
Active

getHouseholdDataReference (active)

URL:
/api/getHouseholdDataReference.php
Synopsis:
Returns a set of allowed values for setting the household attributes
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
N/A
Call:
No arguments required
Response:
{
"profileoptions": {
"ageOfProperty": {
"desc": "Age of Property",
"values": [{"key": "Pre 1851","value": 1},
{"key": "1851-1899","value": 2},
...
{"key": "2000-onwards","value": 8}]
},
....,
"typeOfHotWater": {
"desc": "Type of Hot Water",
"values": [{"key": "Gas Boiler","value": 32 },
... ,
{"key": "Other","value": 36 } ]
}
}
}
Notes:
returns the list of parameters for setting the household attributes. These attributes are used in calculating usage comparisons
State:
Active

getInstant (active)

URL:
/api/getInstant.php
Synopsis:
Will get the instant value for the power consumption of a household. Recommend the usage of getCurrentValuesSummary instead.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID
Returns:
A Json object or error message. On success the json object contains the last reading time (ms since epoch), the reading ( W ) and the age of the reading (s).
Call:
{"securitykey":"HID HASH","timestamp":CURRENT TIMESTAMP,"appID":"YOUR APPID","householderID":"HID"}
Response:
{"last_reading_time":1336039451000,"reading":317,"age":8}
Notes:
Returns the last reading time (ms since epoch), the reading ( W ) and the age of the reading (s).
Note that no comparison is returned even though that was specified in a previous document. Am assuming that this will be resolved at some point soon. If you require this please contact Hildebrand directly.
State:
Active

getMAC (active)

URL:
/api/getMAC.php
Synopsis:
Will get the list of MACs as a listOfMACs for a valid householder ID (HID)
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID
Returns:
(listofMACs) - list of macs( with supporting data) for the given household
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT TIMESTAMP,
"householderID":"HID",
"appID": "'APPID"
}
Response:
{ "listOfMacs":[
{"listofchannels":[],
"mac":"0004A34E7B42",
"personality":"E1",
"status":"unpaired",
"ts":1336044360,
"type":"EEEHub",
"version":"v1.1.0"}
]}
Notes:
For clarification of the various fields returned see the Device Status section below.
State:
Active

getMACStatus (active)

URL:
/api/getMACStatus.php
Synopsis:
Retrieves the device status for a given MAC
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hash) securitykey, (appID) appID, (MAC) mac_address
Returns:
a listOfMacs array with a single entry
Call:
{"securitykey":"HASH",
"timestamp":CURRENT TIMESTAMP,
"mac_address":"MAC",
"appID": "'APPID"
}
Response:
{"listOfMacs": [{"listofchannels":null, "mac":"0004A3679326", "personality":"E1", "status":"unpaired", "ts":1343040898, "type":"EEEHub", "version":"v1.0.1"}]}
Notes:
For clarification of the various fields returned see the Device Status section below.
State:
Active

getMonth (active)

URL:
/api/getMonth.php
Synopsis:
Retrieves the historical timeseries of consumption data for a household for the previous month. Data will be returned at a day level of resolution.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset, [(int) getPreviousPeriod], [(bool) cache], [(data_type) dataType]
Returns:
JSON object OR error. The json object consists of a list of timestamps (milliseconds from epoch), each with an array of consumption values. array[0] is the value for the current period, array[1] is the corresponding value from 24 hours previously. The units are kW.
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT_TS,
"appID":"APPID",
"householderID":"HOUSEHOLD ID"}
Response:
{"status":"ok",
"data":{"1335892740000":[0.18,0.24],
.... ,
"1335979140000":["undef",0.18]}}
Notes:
offset should be the number of minutes away from UTC. e.g. BST (GMT+1) should be -60 )
If getPreviousPeriod is > 0 the previous month's consumption will be returned as well, the previous data is returned by default.
The default data_type is 'kwh'
If data is missing for a given point 'undef' will be returned.
Note that the consumption values in this case are the kWh values for each hour of the day
The timestamps will have been adjusted to your timezone as specified in your offset argument - do not do any more conversion on them
If the offset is not passed the timezone will default to London/Europe.
As month lengths vary we return the last 28 days only as this makes comparison easier. If you need real calendar months use the getTimeSeries query.
If you this doesn't meet your requirements please use getTimeSeries which enables you to build a custom query
We cache for a sensible time to improve performance, it is recommended to not switch off the cache.
State:
active

getPulse (active)

URL:
/api/getPulse.php
Synopsis:
Gets the pulse rate for a given IR clamp.
Version:
1
Last Modified:
September 13 2013 16:21:28.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) sid
Call:
{"appID":"YOUR APPID","securitykey":"HID HASH","timestamp":'CURRENT TIMESTAMP',"householderID":"HID", "sid":12342}
Response:
{'status':'ok', 'pulses':1000}
Notes:
The sid (sensor ID) is required.
State:
active

getStatus (active)

summary (active)

URL:
/api/summary.php
Synopsis:
Gets summary data a given hid
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (string) type, (int) offset
Response:
returns an array of summary data. The type is D,G or DG for combinations of demand and generation
Notes:
This is a helper function for wattson. It's not otherwise supported, sorry.
State:
Active

getTariff (active)

URL:
/api/getTariff.php
Synopsis:
Returns the tariff structure(s) for the HID supplied ( limited by optional sid).
Version:
2.0
Last Modified:
September 23 2013 15:20:39.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, [(string)channel], [(int)sid]
Returns:
A JSON Tariff object ( see example below ) or JSON error message.
Call:
{"securitykey":"HID HASH",
"appID":"YOUR APPID",
"timestamp": CURRENT TIMESTAMP,
"householderID":"HOUSEHOLD ID",
"channel":"PWER",
"sid": "SENSOR ID"
}
Response:
[
{
"channel": "PWER",
"hid": "b3e6327dd610638d82cffd41228b21bf",
"id": "17",
"sid": "0",
"tariff": {
"billing": {
"cycleLength": "1",
"cycleUnits": "1",
"starts": "2013-01-01 00:00:00",
"timezoneBill": "0",
"timezoneReadings": "0"
},
"name": "Electricity Standard",
"plan": [
{
"planDetail": [
{
"rate": 13.381
},
{
"combined": 21.998,
"units": 720
}
]
}
],
"utility": "British Gas"
}
}
]
Notes:
If sid is omitted then the tariffs associated with all channel sids are returned.
Channel defaults to PWER.
State:
active

getTimeSeries (active)

URL:
/api/getTimeSeries.php
Synopsis:
Retrieves the historical timeseries of consumption data for a household over the specified period.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset, (ts)fromTime, (ts)toTime, (aggPeriod)aggPeriod, (aggFunc)aggFunc, [(data_type) dataType], [(bool) cache]
Returns:
JSON object OR error. The json object consists of a list of timestamps (milliseconds from epoch), each with an array of consumption values. array[0] is the value for the current period
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT_TS,
"appID":"APPID",
"householderID":"HOUSEHOLD ID"}
Response:
{"status":"ok",
"data":{"1335892740000":[0.18],
.... ,
"1335979140000":["undef"]}}
Notes:
offset should be the number of minutes away from UTC. e.g. BST (GMT+1) should be -60 )
The default data type is 'kwh'
If data is missing for a given point 'undef' will be returned.
The timestamps in the response will have been adjusted to your timezone as specified in your offset argument - do not do any more conversion on them
fromTime and toTime must be supplied as seconds since the unix epoch in localtime ( NOT UTC ). fromTime must be before toTime
If you this doesn't meet your requirements please use getTimeSeries which enables you to build a custom query
Cache is optional and defaults to true, if there is more than one call to this for a given hid then set to false.
State:
active

getWeather (active)

URL:
/api/getWeather.php
Synopsis:
Gets the current weather for the location of the HID.
Version:
1.0
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (string) city, (string) country
Returns:
A JSON object containing the weather details
Call:
{"appID":"APPID", "securitykey":"HID_HASH", "timestamp":'UTC TIMESTAMP', "householderID":"HID", "city":"beijing", "country":"china"}
Response:
{"cloudcover":"75", "humidity":"69", "observation_time":"10:13 AM", "precipMM":"0.0", "pressure":"1011"," temp_C":"21", "temp_F":"70", "visibility":"5", "weatherCode":"143", "weatherDesc":[{"value":"Mist"}], "weatherIconUrl":[{"value":"ICON URL"}], "winddir16Point":"SSE", "winddirDegree":"160", "windspeedKmph":"11", "windspeedMiles":"7", "location":"Beijing, China"}
Notes:
Returns the current weather for the requested city.
May change this in the future to use a geocoded location of a HID, but I beleive this is sufficient for now.
Note that we use world weather online for this service and some restrictions apply: "If you intend to use our free weather data on your mobile apps like iPhone, or on a desktop widget or on any other medium apart from website then the only mandatory credit is World Weather Online.
If you intend to use our free weather data on website then we require a link back from that website and World Weather Online clearly mentioned in the title of the link."
A full list of weather conditions can be found here: wwoConditionCodes.txt. This corresponds to the weatherCode Field.
State:
Active

getWeek (active)

URL:
/api/getWeek.php
Synopsis:
Retrieves the historical timeseries of consumption data for a household for the previous week. Data will be returned at a hour level of resolution.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset, [(int) getPreviousPeriod], [(bool) cache], [(data_type) dataType]
Returns:
JSON object OR error. The json object consists of a list of timestamps (milliseconds from epoch), each with an array of consumption values. array[0] is the value for the current period, array[1] is the corresponding value from 24 hours previously. The units are kW.
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT_TS,
"appID":"APPID",
"householderID":"HOUSEHOLD ID"}
Response:
{"status":"ok",
"data":{"1335892740000":[0.18,0.24],
.... ,
"1335979140000":["undef",0.18]}}
Notes:
offset should be the number of minutes away from UTC. e.g. BST (GMT+1) should be -60 )
If getPreviousPeriod is > 0 the previous week's consumption will be returned as well, the previous data is returned by default.
If data is missing for a given point 'undef' will be returned.
The default data type is 'kwh'.
Note that the consumption values in this case are the kWh values for each hour of the day
The timestamps will have been adjusted to your timezone as specified in your offset argument - do not do any more conversion on them
If the offset is not passed the timezone will default to London/Europe.
If you this doesn't meet your requirements please use getTimeSeries which enables you to build a custom query
We cache for a sensible time to improve performance, it is recommended to not switch off the cache.
State:
active

getYear (active)

URL:
/api/getYear.php
Synopsis:
Retrieves the historical timeseries of consumption data for a household for the previous year. Data will be returned at a month level of resolution.
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) offset, [(bool) cache], [(data_type) dataType]
Returns:
JSON object OR error. The json object consists of a list of timestamps (milliseconds from epoch), each with an array of consumption values. array[0] is the value for the current period.
Call:
{"securitykey":"HID HASH",
"timestamp":CURRENT_TS,
"appID":"APPID",
"householderID":"HOUSEHOLD ID"}
Response:
{"status":"ok",
"data":{"1335892740000":[0.18,0.24],
.... ,
"1335979140000":["undef",0.18]}}
Notes:
offset should be the number of minutes away from UTC. e.g. BST (GMT+1) should be -60 )
If data is missing for a given point 'undef' will be returned.
The default data type is 'kwh'
Note that the consumption values in this case are the kWh values for each week of the year
The timestamps will have been adjusted to your timezone as specified in your offset argument - do not do any more conversion on them
If the offset is not passed the timezone will default to London/Europe.
If you this doesn't meet your requirements please use getTimeSeries which enables you to build a custom query
We cache for a sensible time to improve performance, it is recommended to not switch off the cache.
Unstable as problem with the underlying calendar.
State:
active

setBudget (active)

URL:
/api/setBudget.php
Synopsis:
Sets a value for the monthly budget for a HID
Version:
1
Last Modified:
September 13 2013 09:53:29.
Arguments:
(tsUTC) timestamp, (hid_hash) securitykey, (appID) appID, (HID) householderID, (int) budget
Call:
{"appID":"YOUR APPID",
"securitykey":"HID HASH",
"timestamp":'CURRENT TIMESTAMP',
"householderID":"HID",
"budget":20.12}
Response:
{'status':'ok', 'monthly_budget':20.12}
Notes:
The budget value should be in pounds and pence ( or just pounds ).
Once set the budget can be retreived using the getBudget Call.
State:
Active

Data Types

Definitions of the various data types and structures.

aggPeriod

Predefined periods over which the data is aggregrated. Valid periods:

  • day
  • week
  • month
  • year
  • minute
  • 15minute
  • 30minute
  • hour

aggFunc

Valid aggregation functions

  • avg
  • sum

avg will return the average usage in the time period, sum will provide the total (in kWh ).

appID

This is the application ID issued to you by energyhive. It is also used in the generation of the security key.

bool

true OR false

clampType

There are currently two supported clamp types. Can be either 'E1' for efergy clamps or 'CC' for CurrentCost. This list may increase in the future. ( May provide a getValidClamps method. )

hash

A security key hash.
This is a 16 character hexidecimal string generated from the UTC timestamp, Shared secret ( provided by energyhive) and appID
To generate the hash concatentate the aforementioned items and generate an md5 hash from the resultant string, only the rightmost 16 characters are required.
An example in php: $hash = substr( md5($timestamp. $shared_secret. $appID), -16); Note that the order of concatentation matters and the timestamp in the query and in the hash must be identical.

hid_hash

A security key hash.
This is a 16 character hexadecimal string generated from the UTC timestamp, Shared secret ( provided by energyhive), appID and HID
To generate the hash concatentate the aforementioned items and generate an md5 hash from the resultant string, only the rightmost 16 characters are required.
An example in php: $hash = substr( md5($timestamp. $shared_secret. $appID. $hid), -16); This is similar to the type with the addition of the user's HID. This form of hash is typically used wherever the HID is passed as a paramter
Note that the timestamp in the query and in the hash must be identical.

HID

The HID is the household identifier and associates one or more MACs with a household. The HID is generated as a result of the registerMAC call.
A HID is a 32 character hexadecimal string.
It is the application's responsibility to maintain the mapping of users and household IDs and to manage authentication unless you have a separate agreement with energyhive.

int

A 32 bit signed integer.

listOfClamps

Either a single clamp id e.g. "3090" or a comma-separated list of of clamps e.g. "3090,1234,432"

MAC

A unique 12 digit hexadecimal string that identifies the Hub hardware. Found on the back of the Hub device.

numeric

A number, either and int or float. Should be positive.

period

Predefined periods over which the data should be gathered. Valid periods:

  • day
  • week
  • month
  • year
  • custom

Where a custom period is defined there will be additional supporting info required - typically a start and end time.

ts

This is a timestamp and is in the form of seconds past the unix epoch ( 1st Jan 1970 00:00:00). This should be set as localtime, not UTC.
See also: Offset

tsUTC

This is a timestamp and is in the form of seconds past the unix epoch ( 1st Jan 1970 00:00:00). This should be set in UTC. Old queries will not be honoured.