Note On Using the Enphase Power Today Method

Update: June 2015: In the move from v1 to v2 of the API, the power_today method was removed. See the migration guide. Use the stats method instead as show in Working with Your Solar Array Data Using the Enphase API. This information in this post will be kept for archival.

In a previous post Working with Your Solar Array Data Using the Enphase API we talked about using Enphase API data to retrieve data about a solar array and use the data for presentation in a web page. One of the problems (not apparent on first glance) is that the data didn’t have a timestamp. Instead, we were assigning a timestamp equal to the time we made the request.  Our assigned timestamp does not equal the time the data was last updated.

Problem

We use the summary() method to return the energy_today value (Wh), but there is no useful timestamp that indicates as of what time the data is valid. The power_today() method returns values for the full day. Can we get a timestamp from this data? How is this data related to the summary() request?

Solution

We can use the power_today() method to return a timestamp. Furthermore, the data returned from the power_today() method “seems” to be track to the energy_today, but delayed.

Details

Step 1. Get the output of both the summary() and power_today() methods at the same time. In the example outputs below, it is 14:00 (military time). We’ll call this time the request_time.

{"energy_week":34865,"energy_month":94405,"modules":14,"current_power":477,"summary_date":"2013-01-20T00:00:00-08:00","source":"microinverters",
"energy_lifetime":95939,"system_id":XXXXXX,"energy_today":5121}
{"first_interval_end_date":"2013-01-20T00:05:00-08:00","production":[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,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,0,0,5,10,13,17,27,41,51,60,70,77,85,101,116,129,145,156,170,194,225,260,289,330,355,348,336,310,301,344,397,409,393,379,388,401,396,386,364,351,379,419,475,518,512,611,936,1597,2038,1988,2238,2322,2180,2033,2033,2011,1684,1424,1646,1811,1944,2104,2125,2171,2258,2239,2100,1916,1610,1236,1013,924],"interval_length":300}

Step 2. In the power_today() data, we see see that the interval_length is 300 (5 minutes) and first_interval_end_date was at 5 minutes after midnight. So the number of data points indicate the last time the data was updated. In this case, 5 min * 164 points / 60 min = 13.67 or in hh:mm 13:40. We’ll call this the calculated timestamp.

Note, if first_interval_end_date were not equal to interval_length, the timestamp calculation would be a bit more complicated. The more general calculation requires this fact to be taken into account and looks like this:

(Count(data points) * interval_length) ) / 60 min + (first_interval_end_date - midnight ) / 60 min = hours offset

But for the time of reporting we are doing here we can stick with the simpler formula:
(Count(data points) * interval_length) ) / 60 min

Step 3. In the power_today() data, we now sum the data points and get 58924. (Import as CSV into Excel.) The summed value is Watts, to get Watt hours we would take the interval for each data point multiplied by the value of the Watts, sum, and divide by 60 min which gives 4910 Wh. We’ll call this the calculated energy_today.

Step 4. In the summary() data, note that the energy_today value is 5121 Wh which is greater than the value for step 3. We’ll call this summary energy_today.

Step 5. Repeat data collection for a little while to see that the calculated energy_today is about 5-10 minutes behind in this small example. It might be more in different circumstances. Also, who knows what processing might be going on with the summary energy_today value.

request_time	calculated timestamp	calculated energy_today	summary energy_today
14:00	13:40	4910	5121
14:10	13:55	5142	5257
14:15	14:00	5205	5364
14:20	14:05	5282	5447
14:25	14:10	5377	5557
14:30	15:25	5481	5557*
14:35	15:20	5702	5869

* We just happened to catch a glitch where the value did not update, which can happen.
So on first glance it looks like we can use the power_today() values to help establish a timestamp. You might be thinking, if we are lazy, on average we could say that the summary energy_today has a timestamp of request_time minus 5-10 minutes. That would apply in an ideal world of consistent data updates. But what if the web service stopped reporting new data points because?  In that case, we would want to know this and the calculated timestamp would indicate it.   So, if you are after a more precise timestamp use the calculated timestamp.