Skip to content

Instantly share code, notes, and snippets.

@mbrownnycnyc
Created July 21, 2017 15:19
Show Gist options
  • Save mbrownnycnyc/c68b08a7c303d9e966a4a9892783350e to your computer and use it in GitHub Desktop.
Save mbrownnycnyc/c68b08a7c303d9e966a4a9892783350e to your computer and use it in GitHub Desktop.
Quick intro reference for the Sense Home Energy Monitor thus far undocumented API. This was taken from the Sense Android app version 1.3.7-9be446d, which was available in Google Play store on February 6th, 2017.
-- Authentication --
URL: https://api.sense.com/apiservice/api/v1/authenticate
Method: POST
Fields:
email (your email)
password (your password)
response JSON:
{
"authorized": true,
"account_id": NNN1,
"user_id": NNN2,
"access_token": "t1.4335.4330.blahblah",
"monitors": [{
"id": NNNN,
"time_zone": "America/New_York",
"solar_connected": false,
"solar_configured": false
}],
"bridge_server": "wss://mb1.home.sense.com"
}
-- Device list --
Example: https://api.sense.com/apiservice/api/v1/app/monitors/NNNN/devices
URL: https://api.sense.com/apiservice/api/v1/app/monitors/NNNN/devices
Method: Get
response JSON: (groups of)
[{
"id": "HEXXXXX",
"name": "Unnamed motor 2",
"icon": "UnknownMotor",
"tags": {
"Alertable": "true",
"DeviceListAllowed": "true",
"Mature": "true",
"name_useredit": "false",
"OriginalName": "Unnamed motor 2",
"Revoked": "false",
"TimelineAllowed": "true",
"TimelineDefault": "true",
"Type": "UnknownMotor",
"user_editable": "true"
},
"type": "UnknownMotor"
}]
-- Sense monitor (the actual Sense device) status --
Example: https://api.sense.com/apiservice/api/v1/app/monitors/NNNN/status
URL: https://api.sense.com/apiservice/api/v1/app/monitors/NNNN/status
Method: GET
resposne JSON:
{
"signals": {
"progress": 100,
"status": "OK"
},
"device_detection": {
"in_progress": [],
"found": [{
"icon": "Microwave",
"name": "Microwave",
"progress": 70
}],
"num_detected": 8
},
"monitor_info": {
"serial": "M649XXXXXX",
"online": true,
"version": "1.1.1379-d95b692-master",
"ssid": "WifiNetworkSSID",
"signal": "-29 dBm",
"mac": "a4:d5:xx:xx:xx:xx"
}
}
-- Get usage history --
Example: https://api.sense.com/apiservice/api/v1/app/history/usage?monitor_id=NNNN&granularity=SECOND&start=2017-02-07T01:48:00.000Z&frames=5400
URL: https://api.sense.com/apiservice/api/v1/app/history/usage
Method: GET
fields:
monitor_id (the "id" returned by authenticate)
granularity (timespan unit [acceptable values: SECOND, MINUTE, ???])
start (start time of data in UTC [like 2017-02-07T01:48:00.000Z])
frames (how many data samples you will retreive [default is 5400])
response JSON:
{
"totals": [
[279, 279],
[279, 279],
[279, 279],
..... (many more samples of data)
[1, -1],
[1, -1],
[1, -1]
],
"endOfData": "2017-02-07T02:57:26.000Z",
"start": "2017-02-07T01:48:00.000Z"
}
-- Get trend data --
Example: https://api.sense.com/apiservice/api/v1/app/history/trends?monitor_id=NNNN&scale=WEEK&start=2017-01-30T05:00:00.000Z&read_combined=false
URL: https://api.sense.com/apiservice/api/v1/app/history/trends
Method: Get
fields:
monitor_id (the "id" returned by authenticate)
scale (the bin for data [accepatble values: DAY, WEEK, MONTH, YEAR]
start (start time of data in UTC [like 2017-01-30T05:00:00.000Z]
read_combined
response JSON: (note that many devices are contained within the ../consumption/devices node)
{
"steps": 28,
"start": "2017-02-01T05:00:00.000Z",
"end": "2017-03-01T05:00:00.000Z",
"consumption": {
"total": 51.398094,
"totals": [10.689455, 10.410812, 10.78235, 9.346396, 10.169082, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
"devices": [{
"id": "8cb442c4",
"name": "Bathroom Light Incandescent ",
"make": "",
"location": "",
"icon": "Lighting",
"tags": {
"Alertable": "true",
"DeviceListAllowed": "true",
"Mature": "true",
"name_useredit": "true",
"OriginalName": "Light 1",
"Revoked": "false",
"TimelineAllowed": "true",
"TimelineDefault": "true",
"Type": "Lighting",
"user_editable": "true"
},
"history": [0.03463329, 0.052048903, 0.13162036, 0.045925356, 0.1306975, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
"type": "Lighting",
"avgw": 0.014104479,
"pct": 0.76836586
}
},
"production": {
"total": 0.0
},
"scale": "month"
}
-- Real time data feed --
This is a websocket conversation that updates data multiple times a second.
use "monitor" from authentication:
URL: wss://mb1.home.sense.com/monitors/NNNN/realtimefeed
response websocket data example:
Type: binary
start/end: provided
message: HEXY MCHEXFACE
@mbrownnycnyc
Copy link
Author

I missed the notice for your comment. I assume that it's simply a Y-value on a graph as rendered in the UI.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment