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 report request is limited to retrieving information for up to 25 thermostats with a maximum period of 31 days, per request. 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).

The data in the report is at 5 minute intervals for a whole day. The data represented in terms of runtime is for the 5 minute interval (up to 300 seconds).

This request should not be made at an interval of less than 15 minutes as the data on the server only changes every 15 minutes. Use the Thermostat Summary (Polling) request to determine if the thermostat status revision has changed.

The report data comes back in thermostat time.

When making this request, ensure your client supports GZIP compression. A lot of data may be transferred in the response.

Report Start/End Intervals

Runtime 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.

Report Dates & Times

The times returned by the runtime 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

Show code sample in:
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":""
   }
}

Back To Top