User Tools

Site Tools


jsonpinterface

This is an old revision of the document!


mySmartGrid JSONP Interface

This page specifies the JSONP interface that makes it possible for JavaScript clients from other Web domains to query sensor measurements from mySmartGrid.

Below, we describe how the interface can be used to plot measurements on a chart using the Dygraphs library. You can see the example we are building here.

How to Use

The first step is to load the Dygraphs libraries:

<script type="text/javascript"
        src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/dygraph-min.js">
        </script>
<script type="text/javascript"
        src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/dygraph-canvas-min.js">
        </script>
<script type="text/javascript" 
        src="https://www.mysmartgrid.de/sites/all/modules/logger/js/dygraph/rgbcolor.js">
        </script>

Then, you need to declare a <script> tag in your HTML page, as follows.

<script type="text/javascript" 
  src="https://www.mysmartgrid.de/jsonp/sensor/5715a57b0c8ec958727ab3bb206d8b6e?
  interval=hour&unit=watt&token=d3a16238d92456bb0f6727743275dce0&data_function=getDemoData">
</script>

The response for the HTTP request performed by this tag contains JavaScript functions that return pairs of timestamps and values formatted as JSON arrays, as seen below.

function getDemoData(){
  return [[1375800420,309.0909090924],[1375800480,310.90909091040004],[1375800540,303.75]];
}

The URL informed in the src attribute must have the following structure:

https://www.mysmartgrid.de/jsonp/sensor/<sensor id>?<parameters>

You can discover the id of your sensor by visiting the sensors page.

The table below informs which parameters can be informed in the URL.

Parameter Description Possible Values Note
unit The unit in which the measurement results will be shown Watt, kWh, Wh Optional, default: Watt
resolution The resolution of the measurement results. minute, 15min, hour, day, week Optional, default: minute
start First timestamp of the query period. Unix timestamp Required if end is also informed.
end First timestamp of the query period. Unix timestamp Required if start is also informed.
interval An alternative way of representing a standard period of time that ends right now, for example: the past 1 hour (60 min). hour, day, week Required only if start and end are not informed. Default: hour
token The sensor authentication token. Please visit the sensors page Mandatory
data_function The name of the JavaScript function that your code will be able to call in order to get the measurements. A JavaScript function name. Optional, default: get<sensor id>
callback_function The name of the JavaScript function from your code that will be called, passing the measurements array as argument. A JavaScript function name. Optional


Now, the data can be used in your page. Please, create a <div>, where the chart will be placed.

<div id="chartDiv" style="width:400px; height:200px;"></div>

Finally, create the Dygraph object in another <script> tag:

<script type="text/javascript">
 
  new Dygraph(
    
    // chart div
    document.getElementById("chartDiv"),
 
    // demo sensor measurements
    getDemoData(),
 
    // chart format
    {
      fillGraph: true,
      fillAlpha: 0.15,
      xAxisLabelWidth: 100,
      xAxisLabelFormatter: function(ms) { return (new Date(ms * 1000)).toLocaleTimeString(); },
      xValueFormatter: function(ms) { return (new Date(ms * 1000)).toLocaleTimeString(); },
      xTicker: Dygraph.dateTicker,
      xPixelsPerLabel: 100
    }
  );
</script>

Click here to see the result in a new page.

Security Considerations

The token grants you access to the sensor. Everyone who knows the token can also see your sensor values, so you must protect it. As you can see above, our API only works via HTTPS. In order to protect the token you should not expose it to others, i.e. by embedding the JavaScript from above in unencrypted HTML pages of your application.

We intend to replace the token by an application-specific token in the future. This app-token will simply replace the access token from above but will be issued on a per-app basis. This will allow a mySmartGrid user to delete an application's access from his data by simply revoking the corresponding app-token.

jsonpinterface.1375864891.txt.gz · Last modified: 2013/08/07 10:41 by mysmartgrid