GET Meter Report
URL: /meterReport
Accessible by: Smart, EMS, Utility accounts.
Restrictions: Thermostat needs to be paired with a ZigBee meter.
Retrieves the historical meter reading information for a selection of thermostats.
The data in the report is formatted as a time-series of 5 minute intervals for a whole day. There are 288 intervals per day. The values supplied for any given 5-minute interval is the value at the start of the interval and is not an average.
The report request is limited to retrieving information for up to 25 thermostats with a maximum period of 31 days, per request.
When making this request, ensure your client supports GZIP compression. The amount of data returned is considerable for 31 days of data for 25 thermostats (25 thermostats * 288 intervals per day * 31 days = 223,200 rows of data).
API USAGE LIMITS
- Use the Thermostat Summary (Polling) request to determine if the Runtime Revision value has changed before making repeated requests for runtime reports.
- DO NOT request report data at an interval quicker than once every 15 minutes, which is the shortest interval at which report data can change. There may also be a delay of up to an hour before the most recent report data is made available via the API.
- DO NOT have more than 1 open HTTP request for reports at any given time; wait until the ecobee server has responded before issuing additional API requests.
Report Start/End Intervals
Report data is stored in 5 minute intervals. To compute the desired interval, take the interval and multiply it by 5 (minutes). For example interval 0 is 00:00:00, interval 12 is 60min or 01:00:00 and interval 264 is 1320min or 22:00:00. See the What is a runtime interval? FAQ article for additional calculation help.
Report start & end intervals are based on UTC however the timestamps in the report data are in thermostat time.
Report Dates & Times
The times returned by the report are in thermostat time and Daylight Savings (DST) is applied to the date and time returned in the report if the thermostat's settings indicate that DST is enabled.
Report Temperature Readings
Temperature value readings will be returned in degrees F.Utility Pricing Information
Utility pricing information is defined by the utility. If none is available, pricing and tier information will be unavailable.
Request Properties
| Property | Version | Type | Required | Description |
|---|---|---|---|---|
| selection | 1 | Object | Yes | The Selection Object. Must be selectionType = 'thermostats' and selectionMatch = a CSV of thermostat identifiers. |
| startDate | 1 | Date | Yes | The UTC report start date. |
| startInterval | 1 | Integer | No | The 5 minute interval to begin the report on. The interval can be determined by multiplying the interval by 5. Range: 0-287 Default: 0 |
| endDate | 1 | Date | Yes | The UTC report end date. |
| endInterval | 1 | Integer | No | The 5 minute interval to end the report on. The interval can be determined by multiplying the interval by 5. Range: 0-287 Default: 287 |
| meters | 1 | String | Yes | A CSV string of meter types. See Meter Types |
Response Properties
| Property | Version | Type | Description |
|---|---|---|---|
| startDate | 1 | Date | The report UTC start date. |
| startInterval | 1 | Integer | The report start interval. |
| endDate | 1 | Date | The report UTC end date. |
| endInterval | 1 | Integer | The report end interval. |
| meters | 1 | String | The CSV list of meter types from the request. |
| reportList | 1 | MeterReport [] | A list of thermostat meter reports. |
Meter Types
The following meter types are supported:
| Column Name | Description |
|---|---|
| energy | Energy meter |
Meter Data Columns
The following columns may be returned in the report data.
| Column Name | Data Type | Units | Description |
|---|---|---|---|
| date | Date | n/a | The date in thermostat local time. |
| time | Time | n/a | The time in thermostat local time. |
| tier | String | n/a | The tier name or empty value if no tier pricing has been defined by the utility. |
| energyConsumption | Float | kWh | The energy consumption as reported by the meter in the interval period. |
| energyCost | Float | $0.01 (cents) | The energy cost will only appear only if the utility has defined tier pricing information. Cost is for the interval period. |
Example Request:
Request Body
NOTE: Request body is not encoded for example purposes.
HEADERS:
Content-Type: application/json;charset=UTF-8
Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
REQUEST:
GET https://api.ecobee.com/1/meterReport?format=json&body={"startDate": "2010-01-01","endDate": "2010-01-02","meters": "energy","selection":{"selectionType":"thermostats","selectionMatch":"123456789012"}}
The pretty formatted body of the request is:
{
"startDate": "2013-04-04",
"endDate": "2013-04-04",
"meters": "energy",
"selection": {
"selectionType": "thermostats",
"selectionMatch": "123456789012"
}
}
Sample API Call
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/meterReport?format=json&body=\{"startDate":"2010-01-01","endDate":"2010-01-02","meters":"energy","selection":\{"selectionType":"thermostats","selectionMatch":"123456789012"\}\}'
Example Response:
{
"reportList":[
{
"thermostatIdentifier":"123456789012",
"meterList":[
{
"meterType":"energy",
"columns":"date,time,tier,energyConsumption,energyCost",
"data":[
"2013-04-04,00:00:00,off-peak,0.692,6.78",
"2013-04-04,00:05:00,off-peak,0.041,0.02",
"2013-04-04,00:10:00,off-peak,0.086,0.11",
"2013-04-04,00:15:00,off-peak,0.053,0.24",
"2013-04-04,00:20:00,off-peak,0.079,0.45",
"2013-04-04,00:25:00,off-peak,0.034,0.0",
"2013-04-04,00:30:00,off-peak,0.028,0.21",
"2013-04-04,00:35:00,off-peak,0.061,0.15",
"2013-04-04,00:40:00,off-peak,0.07,0.05",
"2013-04-04,00:45:00,off-peak,0.038,0.41",
"2013-04-04,00:50:00,off-peak,0.024,0.27",
"2013-04-04,00:55:00,off-peak,0.078,0.47",
"2013-04-04,01:00:00,off-peak,0.017,0.21",
"2013-04-04,01:05:00,off-peak,0.0090,0.31",
....snip...
]
}
]
}
],
"status":{
"code":0,
"message":""
}
}