Page 1 of 1

EKM Push Summary API

Posted: Mon May 18, 2015 5:24 pm
by Adam
If you're interested in a long term data set that is available to all EKM Push users then this may interest you. We've been keeping this under wraps until now but we feel that it would be best to release in beta, so that we can get an idea of user and developer interest. Our Push Summary system exists in parallel with our real-time Push data system. This is how encompass.io gets its historical data for the Info, Calendar and Comparison widgets. We're happy to have you as beta testers but we reserve the right to restrict access to this API in the future. We feel that this is much more than we have been providing for free to our customers, so we are trying to determine how much or if to charge for it.

The system works by taking the real-time data and summarizing it into 15 minute chunks, which are available as is or are assembled into hour, day, or monthly summaries. Below are a bunch of example API calls that highlight the different options available. These can often times be combined to give you the exact format, data point, time frame, timezone, etc. We don't have much documentation on this system at this point so you will have to be creative about how you can combine different API call elements.

These calls use our public EKM Push Key and Meter numbers. Swap in your own to call your personal data instead.

15 minute:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=json

hour:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=hr&format=json

day:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=dy&format=json

week:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=wk&format=json

month:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=mo&format=json

range (today’s date to same date last month by default):
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=range&format=json

variable date range (in this case: January 4th at 8:20pm to February 8th at 8:20pm):
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=range&format=html&timezone=America/Denver&start_date=2015-01-04%2020:15&end_date=2015-02-08%2020:15

month to Month day offset (5 days in this case):
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=mo5&format=json&limit=4

xml:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=xml

html:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=html

csv:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=csv

multiple meters:
http://summary.ekmpush.com/summary?meters=10068,10054&key=MTAxMDoyMDIw&report=15&format=json

specific fields:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&fields=kWh_Tot_Last,kWh_Tot_Diff,kWh_Tot_Min,kWh_Tot_Max&format=json&report=15

timezone adjusted (http://en.wikipedia.org/wiki/List_of_tz_database_time_zones):
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=json&timezone=America/Los_Angeles

specific start date/time:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=json&start_date=2014-11-18%2020:15

specific end date/time:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=json&end_date=2014-11-18%2020:15

limit number of records (will default to a limited number of records unless explicitly set):
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=json&limit=2

offset:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=dy&format=json&offset=3

specific host:
http://summary.ekmpush.com/summary?meters=10068&key=MTAxMDoyMDIw&report=15&format=json&offset=0&limit=10&host=col.c1.ekmmetering.com

*Note: the number of records returned will default to a limited number. If you want more records than the default, then add the &limit=**** number and set it o the number of records that you want returned.

Re: EKM Push Summary API

Posted: Wed Jun 03, 2015 12:10 am
by sensij
Thanks for sharing this. It is a great way to recover data that I missed.

Re: EKM Push Summary API

Posted: Wed Jul 22, 2015 3:04 pm
by Jameson
If you are interested in the long term data set, be sure to check out the Summary API Builder tool here: http://summary.ekmpush.com/api-builder

It could be a little rough around the edges, so please let us know if you spot any glaring issues.

Have fun with it!!

Re: EKM Push Summary API

Posted: Thu Oct 01, 2015 5:55 am
by smladen
Can you please explain details of returned fields or point me to document with explanation?
E.g.
"kWh_Tot_DeltaMin": 0,
"kWh_Tot_DeltaMax": 0.1,
"kWh_Tot_Min": 102530.9,
"kWh_Tot_Max": 102531.1,
"kWh_Tot_Diff": 0.2,
What is my kWh_Tot?

Re: EKM Push Summary API

Posted: Thu Oct 01, 2015 10:02 am
by Jameson
Hello Smladen,

Welcome to the forum. We would be happy to answer any of these data definition questions about the Summary API here.

"kWh_Tot_DeltaMin": 0, This is the smallest kWh increment between real-time reads for the time period. This number should always be either 0 or a positive number. If it is a negative number over -0.1 this would indicate an issue.

"kWh_Tot_DeltaMax": 0.1, This is the largest kWh increment between real-time reads for the time period. For example, the kWh real-time data was 50.1, 50.1, 50.1, 50.3, 50.4, 50.4 the Delta_Min would be 0 and the Delta_Max would be 0.2 (because of the 50.1 to 50.3 reads)

"kWh_Tot_Min": 102530.9, This is the lowest kWh read for the time period you have requested. If you are looking at Month data, this should be the first and therefore lowest kWh read of the month.

"kWh_Tot_Max": 102531.1, This is the highest kWh read for the time period you have requested. If you are looking at Day data, this should be the last and therefore highest kWh read of the Day.


"kWh_Tot_Diff": 0.2, This is the Difference in kWh from the first kWh read in the time period you have requested to the last kWh in the time period you have requested. So for example, if you have called Days, the kWh_Tot_Min could be 1000.0 the kWh_Tot_Max could be 1008.0 the kWh_Tot_Diff would be 8.0. One example of how we use this is we use kWh_Tot_Diff to chart all of the kWh for each individual day in a month like this:

http://widget.ekmmetering.com/EKM2/?rea ... v_reads=48


What is my kWh_Tot?

If you want to know your kwh Tot for this minute right now, you can use the Real-Time API: http://www.ekmmetering.com/developer-portal/

If you want to know what it was an hour ago, a day ago, or a month ago (or any time in between) you can use the summary API. In the example above your latest kWh_Tot = 102531.1

Re: EKM Push Summary API

Posted: Tue Nov 03, 2015 1:13 pm
by Jameson
Heads up that we have made a change to the Summary API. We now include a * after the "fields" filter names:

Here are some new examples, that filter for kWh, or kWh_Tot:
specific fields:
http://summary.ekmpush.com/summary?mete ... &report=15

or this:

http://summary.ekmpush.com/summary?mete ... &report=15

or this:

http://summary.ekmpush.com/summary?mete ... &report=15

Re: EKM Push Summary API

Posted: Fri Nov 06, 2015 9:56 am
by Jameson
Say for example that you get billed on the 18th of each month, so you want to know your electricity usage or water usage from the 18th to the 18th of the following month. In this case you can use report=mo18


http://summary.ekmpush.com/summary?mete ... 8&limit=10

This will return kWh data for up to the last 10 months from the 18th to the 18th. Here is one record out of 10:
Screenshot 2015-11-06 08.36.49.png
Screenshot 2015-11-06 08.36.49.png (38.52 KiB) Viewed 45593 times
This is the summarized data record based on 2,673,014 real-time meter reads from v.3 meter 10068 from August 18th 2015 to September 18th 2015, filtered for kWh_Tot only.

If you want to know the usage for this period of time you can look at Dif=1864.3 (in the screenshot above). This means that from August 18th to September 18th this meter measured 1864.3 Total kWh. (the kWh read at the end of this period of time was 101934.7, the maximum forward increment of this time period DMx was 0.1 kWh)

Hope this helps,

Re: EKM Push Summary API

Posted: Thu Jan 14, 2016 5:47 pm
by Jameson
Id like to add what the real-time values (watt, volts, amps, etc) look like in Summaries:

Here is the example for Total Watts:

RMS_Watts_Tot_Last: This is the latest value (the newest value) for the given time period.
RMS_Watts_Tot_Average: This is the average value for Total Watts within the given time period, you can find the average Total Watts per day for example.
RMS_Watts_Tot_StdDev: This is Standard Deviation. I think wikipedia can do a better job of explaining this than I: https://en.wikipedia.org/wiki/Standard_deviation
RMS_Watts_Tot_DeltaMin: This is the most the the Total Watts dropped from one read to the next.
RMS_Watts_Tot_DeltaMax: This is the most the the Total Watts rose from one read to the next.
RMS_Watts_Tot_Min: This is the minimum Total Watts value seen in the time period given. This is useful for finding your base load.
RMS_Watts_Tot_Max: This is the maximum Total Watts value seen in the time period given.
RMS_Watts_Tot_MinTime: This is the timestamp of the read that had the minimum Total Watts value seen in the time period given. Timestamp is given in UTC + ms time.
RMS_Watts_Tot_MaxTime: This is the timestamp of the read that had the Maximum Total Watts value seen in the time period given.

Re: EKM Push Summary API

Posted: Tue Apr 26, 2016 3:17 pm
by Adam
The Realtime API, Summary API, and RS-485 communication protocols are now documented here: http://documents.ekmmetering.com/api-docs/

We recommend that you use this link and documentation from now on as it should provide much clearer explanations for the options available to you with our API. It also provides code snippet examples of our API wrapped in various programming languages. These languages include Command Line, Ruby, Python, PHP, Perl, Java, C, NodeJS, and Javascript. We want to encourage 3rd party use of our meter data, so the data and our APIs are 100% free and open to all developers.

I also want to mention that if you come up with a useful application or service, that uses the EKM Push APIs and that you would like to share with our customers, we have a App Store for this purpose. You can see it here: http://www.ekmmetering.com/solutions/push-apps.html