EKM Push Summary API

For more advanced meter data users. Learn from others and ask questions about how to read meters, how to use the EKM Push Data, and how to display the meter data in useful ways.
Post Reply
Adam
Posts: 5
Joined: Thu Sep 27, 2012 12:54 pm

EKM Push Summary API

Post 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.
sensij
Posts: 7
Joined: Fri May 08, 2015 9:48 am

Re: EKM Push Summary API

Post by sensij »

Thanks for sharing this. It is a great way to recover data that I missed.
Jameson
Posts: 860
Joined: Fri Nov 04, 2011 7:42 pm
Location: Santa Cruz, CA
Contact:

Re: EKM Push Summary API

Post 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!!
Last edited by Jameson on Tue Aug 25, 2015 7:12 pm, edited 1 time in total.
Jameson
EKM METERING
http://www.ekmmetering.com
831.425.7371
smladen
Posts: 1
Joined: Thu Oct 01, 2015 5:37 am

Re: EKM Push Summary API

Post 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?
Jameson
Posts: 860
Joined: Fri Nov 04, 2011 7:42 pm
Location: Santa Cruz, CA
Contact:

Re: EKM Push Summary API

Post 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
Jameson
EKM METERING
http://www.ekmmetering.com
831.425.7371
Jameson
Posts: 860
Joined: Fri Nov 04, 2011 7:42 pm
Location: Santa Cruz, CA
Contact:

Re: EKM Push Summary API

Post 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
Jameson
EKM METERING
http://www.ekmmetering.com
831.425.7371
Jameson
Posts: 860
Joined: Fri Nov 04, 2011 7:42 pm
Location: Santa Cruz, CA
Contact:

Re: EKM Push Summary API

Post 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 45587 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,
Jameson
EKM METERING
http://www.ekmmetering.com
831.425.7371
Jameson
Posts: 860
Joined: Fri Nov 04, 2011 7:42 pm
Location: Santa Cruz, CA
Contact:

Re: EKM Push Summary API

Post 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.
Jameson
EKM METERING
http://www.ekmmetering.com
831.425.7371
Adam
Posts: 5
Joined: Thu Sep 27, 2012 12:54 pm

Re: EKM Push Summary API

Post 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
Post Reply