====== Data Feed API ======
For the ioBridge IO-204 and IO-204-PRO Monitor and Control Modules

===== Introduction =====
Each module that you have linked and registered to your account has a unique Feed URL. When requested, the URL returns a JSON or XML formatted snapshot of your module’s input and output states as well as any META information you have supplied such as Location, Latitude, Longitude, Labeling, and Scaling. The returned data allows for the creation of data logging, charting, custom scaling, mash-ups, and importing into server and client-side scripting. The API is lightweight and allows you to easily extend the ioBridge system data to remote systems, servers, clients, desktops, and applications.

The Data Feed API key is listed under Modules -> (Selected Module) -> API.

We are excited to see how you will extend the data from your module to your applications and services. Visit [[http://www.iobridge.net/projects|www.iobridge.net/projects]] for ideas and to submit your own ideas, comments, and project developments.

Further API documentation can be found on the ioBridge Wiki:  
http://www.iobridge.net/wiki/api

{{:api:iobridge-server-temp.png|}}

//Data Charting with Google Charts and the ioBridge Data Feed API//

===== Extending the API =====
You may extend the data to server-side scripts, desktop applications, and client-side browser-based applications.

Here are some ways you can extend the API into your application:

  * Google Gadgets and Desktop Widgets
  * Windows and Mac Widgets
  * Custom Analog Sensor Scaling
  * Data Charting
  * Data Logging
  * Google Maps
  * Weather Widgets

===== Limitations =====
The feed requests are cached for 10 seconds, which means your application will only return new data every 10 seconds. ioBridge acts a proxy between the world and your module, so you don’t have to worry about your project going viral. We will only link to your module once every 10 seconds regardless of the number of people viewing your application, widget, or website based on the Data Feed API.

===== Change History =====

^Date	^Version	^Changes^
|06-2010	|v2.0	|Changed URL Structure|
|:::|:::|Added SSL Support|
|:::|:::|Added RESTful Interface|
|:::|:::|Added Form POST Support|
|:::|:::|Added IO-204-PRO Support|
|:::|:::|Added new Variable Keys|
|:::|:::|Updated API Rate Limits|
|06-2009	|V1.1	|Changed URL Structure|
|:::|:::|Added XML Support|
|:::|:::|Added Pulse Count Keys|
|12-2008	|V1.0	|Original Data Feed Released|

===== RESTful Interface =====

==== API Key ====

The Data Feed API Key for the IO-204 or IO-204-PRO monitor and control modules are listed under the following section of the ioBridge.com Interface:

//Modules -> (Selected Module) -> API//

==== Formats ====

The possible response formats are JSON and XML. If no format is called, JSON is returned by default.

  * //feed.json//
  * //feed.xml//

==== URI/URL Structure ====


  * http://www.iobridge.com/api/module/feed.(format)
  * http://www.iobridgepro.com/api/module/feed.(format)
==== SSL ====


  * https://www.iobridge.com/api/module/feed.(format)
  * https://www.iobridgepro.com/api/module/feed.(format)

==== HTTP GET ====

To access the Data Feed API using HTTP GET, access the URL using the API Key as a parameter appended to the URL.

  * http://www.iobridge.com/api/module/feed.(format)?key=____IOBRIDGEAPI KEY____

==== HTTP POST ====


There are two ways to access the Data Feed API using HTTP POST.

  * Pass the API Key as parameter using a content type of “application/x-www-form-urlencoded”.
  * Pass the API key using a Custom HTTP Header via the “X-ioBridgeAPIKey” header.

 
==== Keys and Meta Information ====

You set the keys and meta information on the Modules tab for the appropriate  module. Data and configuration entered on the Modules tab are the returned labels  and scaling in the return object. Only I/O Channel modes return data in the feed.

The following keys are available to parse in your feed:
^Key	^Description^
|serial|Module Serial Number|
|label|Entered Module Label|
|lat|Entered Latitude (Decimal Degrees)|
|long|Entered Longitude (Decimal Degrees)|
|location|Entered Location Description|
|datetime|Date and Time of Feed Request|
|status|Status of Module (Offline, Online)|
|channels|Array of Four Module Channel (0,1,2,3)|
|channel|Channel Number |
|label|Entered Channel Label|
|AnalogInput|Scaled Analog Input value (Voltage, Raw, Temperature)|
|AnalogInputRaw|Relative Analog Input Value (0-1023)|
|AnalogInputScale|Selected Scale of Analog Input|
|DigitalInput|Labeled Digital Input State|
|DigitalInputState|Digital Input State (1,0)|
|PulseCountRaw|32-bit Raw Pulse Count on Digital Input Pin (IO-204 C4+ or IO-204-PRO D1+)|
|DigitalOutput|Labeled Digital Output State|
|DigitalOutputState|Digital Output State (1,0)|
|LastSerialInput|Last Serial Data Received by a Serial Smart Board|
|Variable1|8-bit variable space accessed by Onboard Rules (IO-204 C4+ or IO-204-PRO D1+)|
|Variable2|16-bit variable space accessed by Onboard Rules (IO-204-PRO D1+)|


===== Server-side JSON =====
You can safely request your Feed URL from any server-side scripting language like Perl, Python, or PHP that supports JSON. The Feed URL returns the HTTP header of “Content-type: application/json”.

==== JSON Feed URL Example ====
<code>http://www.iobridge.com/api/module/feed.json?key=zTFNFDol7706vSZnuxel</code>

==== JSON Object ====
<code html>
{
"module": {
      	"serial": "24000XXX",
            "label": "ioServer Monitor",
            "lat": "",
            "long": "",
            "location": "Gainesville, FL",
            "datetime": "Dec-24-2008 00:35:22 AM",
            "status": "Online",
            "channels": [
{"channel": "1", "label": "Channel 1", "AnalogInput": "384", "AnalogInputRaw": "384", "AnalogInputScale": "Raw", "DigitalInput": "Off", "DigitalInputState": "0", "DigitalOutput": "On", "DigitalOutputState": "1"},
{"channel": "2", "label": "Channel 2", "AnalogInput": "308", "AnalogInputRaw": "308", "AnalogInputScale": "Raw", "DigitalInput": "Off", "DigitalInputState": "0", "DigitalOutput": "Off", "DigitalOutputState": "0"},
{"channel": "3", "label": "Channel 3", "AnalogInput": "0", "AnalogInputRaw": "0", "AnalogInputScale": "Raw", "DigitalInput": "0", "DigitalInputState": "0", "DigitalOutput": "0", "DigitalOutputState": "0"},
{"channel": "4", "label": "Channel 4", "AnalogInput": "2.737", "AnalogInputRaw": "560", "AnalogInputScale": "Voltage", "DigitalInput": "Off", "DigitalInputState": "0", "DigitalOutput": "Down", "DigitalOutputState": "0"}
                        ]
        }
}
</code>

===== Server-side XML =====
By adding the format parameter to the Data Feed URL, you can alternatively format the results in XML.

==== XML Feed URL Example ====
<code>http://www.iobridge.com/api/module/feed.xml?key=zTFNFDol7706vSZnuxel</code>

==== XML Object ====
<code xml>
<?xml version="1.0"?>
        <module>
            <serial>2400XXXX</serial>
            <label>ioServer Monitor</label>
            <lat></lat>
            <long></long>
            <location>Gainesville, FL</location>
            <datetime>2009-07-03 02:20:36</datetime>
            <status>Online</status>
            <channel_1>
        		<label>Channel 1</label>
        		<AnalogInput>2.737</AnalogInput>
        		<AnalogInputRaw>14</AnalogInputRaw>
        		<AnalogInputScale>Voltage</AnalogInputScale>
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
    	    </channel_1>
            <channel_2>
        		<label>Channel 2</label>
        		<AnalogInput>310</AnalogInput>
        		<AnalogInputRaw>310</AnalogInputRaw>
        		<AnalogInputScale>Raw</AnalogInputScale>
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
    	    </channel_2>
            <channel_3>
        		<label>Channel 3</label>
        		<AnalogInput>256</AnalogInput>
        		<AnalogInputRaw>256</AnalogInputRaw>
        		<AnalogInputScale>Raw</AnalogInputScale>

        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
    	    </channel_3>
            <channel_4>
        		<label>Channel 4</label>
        		<AnalogInput>279</AnalogInput>
        		<AnalogInputRaw>279</AnalogInputRaw>
        		<AnalogInputScale>Raw</AnalogInputScale>
        		<DigitalInput>On</DigitalInput>
        		<DigitalInputState>1</DigitalInputState>
        		<DigitalOutput>Off</DigitalOutput>
        		<DigitalOutputState>0</DigitalOutputState>
            </channel_4>
</module>
</code>

===== Client-side JSON =====
If you are using jQuery or other client-scripting libraries to parse JSON, you have the ability to use JSONP (JSON with Padding) to get JSON from two different domains using Callback.
==== JSONP Callback Data Feed URL ====
<code>http://www.iobridge.com/api/module/feed.json?key=zTFNFDol7706vSZnuxel&callback=?</code>

When callback is used, the Feed URL returns a JSONP object.

==== JSONP Object ====
<code html>
jsonp1230097032945({
        "module": {
            "serial": "24000XXX",
            "label": "ioServer Monitor",
            "lat": "",
            "long": "",
            "location": "Gainesville, FL",
            "datetime": "Dec-24-2008 00:36:40 AM",
            "status": "Online",
            "channels": [
{"channel": "1", "label": "Temperature", "AnalogInput": "103.6", "AnalogInputRaw": "665"
, "AnalogInputScale": "Temp F", "DigitalInput": "On", "DigitalInputState": "1", "DigitalOutput": "Off", "DigitalOutputState": "0"},
{"channel": "2", "label": "Channel Tester", "AnalogInput": "337", "AnalogInputRaw": "337", "AnalogInputScale": "Raw", "DigitalInput": "Hi", "DigitalInputState": "1", "DigitalOutput": "Off", "DigitalOutputState": "0"},
{"channel": "3", "label": "Servo", "AnalogInput": "269", "AnalogInputRaw": "269", "AnalogInputScale": "Raw", "DigitalInput": "On", "DigitalInputState": "1", "DigitalOutput": "On", "DigitalOutputState": "1"},
{"channel": "4", "label": "IR", "AnalogInput": "0", "AnalogInputRaw": "0", "AnalogInputScale": "Raw", "DigitalInput": "0", "DigitalInputState": "0", "DigitalOutput": "0", "DigitalOutputState": "0"}
                        ]
        }
})
</code>

===== Parsing JSON =====
You can get access to any of the data in the JSON Object by parsing out the desired keys.

For example here is a jQuery request and data selection from feed:

<code>
function checkTemp() {
	
	$.getJSON("http://www.iobridge.com/api/module/feed.json?key=zTFNFDol7706vSZnuxel&callback=?",
	function (data) {
        storeTemp(data.module.channels[0].AnalogInput); updateGraph();
	});
		
}
</code>

"data.module.channels[0].AnalogInput" references the scaled analog input value on channel 1 of the IO-204 Module.

If you would want the modules serial number, the reference would be “data.module.serial” using the serial key under module.

===== Client-side Application Step-by-Step =====
From soup to nuts, we wanted to show you a complete application extension of the Data Feed API and the steps involved. Share your projects at www.iobridge.com/projects.

The following projects takes your Feed URL extracts the Scaled Analog Input from Channel 1 and feeds Google Charts to return a Google-o-Meter indicating the current temperature using jQuery.

**Step 1:** Create a new HTML file called //ServerTempNeedle.html//

**Step 2:** Create the HTML frame work – head and body
<code html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html> 
<head> 
<title>ioBridge Server Temperature</title> 
</head> 
<body> 
<div id="container"> 
	<div id="data_graph"></div> 
</div> 
</body> 
</html>
</code>

**Step 3:** Load jQuery from Google JSAPI to the document header
<code javascript>
<script type="text/javascript" src="http://www.google.com/jsapi"></script> 
<script type="text/javascript"> 
    google.load("jquery", "1");
</script> 
</code>

**Step 4:** Add a ready function when the HTML fully loads to check the temperature from the feed and set a timer that will check the temperature every 10 seconds
<code javascript>
$(function() {
	checkTemp(); // Gets initial temperature
	setInterval("checkTemp()", 10000); // Sets a 10 Second timer
});
</code>
 
**Step 5:** Add function that checks the temperature and updates the graph when the data is returned (use your feed URL to get your data or use our public feed to get our server temperature)
<code javascript>
function checkTemp() {
	$.getJSON("http://www.iobridge.com/api/module/feed.json?key=zTFNFDol7706vSZnuxel&callback=?",
	function (data) {
	
			// Channel 1 is the first element in the array
			updateGraph(data.module.channels[0].AnalogInput);	

	});
}
</code>

**Step 6:** Add function to get the Google chart and display it in the “data_graph” division in the document body
<code javascript>
function updateGraph(temp) {

	var newTemp = temp-50;
	newTemp = 100 - newTemp;
	
	var chart_url = "http://chart.apis.google.com/chart?"
	var chart_type = "cht=gom";
    	var chart_size = "&chs=300x200";
	var chart_title = "&chtt=ioBridge Server Temperature";
	var chart_data = "&chd=t:" + newTemp + "&chl=" + temp + " F";
	var url = chart_url + chart_type + chart_size + chart_title + chart_data;
 
	var i = $("<img>").attr("src", url);
	$("#data_graph").empty().append(i);
}
</code>

**Step 7:** Save file and open in web browser such as Safari, Chrome, Firefox, Opera, or Internet Explorer
===== Live Examples =====
  * [[http://www.iobridge.com/ServerTempNeedle.html|ioBridge Server Temperature Needle]]
  * [[http://www.iobridge.com/ServerTempChart.html|ioBridge Server Temperature Chart]]
===== Google Chart - Temperature Meter Source Code =====
<code html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html> 
<head> 
<title>ioBridge Server Temperature</title> 
 
<script type="text/javascript" src="http://www.google.com/jsapi"></script> 
<script type="text/javascript"> 
    google.load("jquery", "1");
</script> 
<script type="text/javascript"> 
    
function updateGraph(temp) {

	var newTemp = temp-50;
	newTemp = 100 - newTemp;
	
	var chart_url = "http://chart.apis.google.com/chart?"
	var chart_type = "cht=gom";
    	var chart_size = "&chs=300x200";
	var chart_title = "&chtt=ioBridge Server Temperature";
	var chart_data = "&chd=t:" + newTemp + "&chl=" + temp + " F";
	var url = chart_url + chart_type + chart_size + chart_title + chart_data;
 
	var i = $("<img>").attr("src", url);
	$("#data_graph").empty().append(i);
}
 
function checkTemp() {
	$.getJSON("http://www.iobridge.com/api/module/feed.json?key=zTFNFDol7706vSZnuxel&callback=?",
	function (data) {
  	    updateGraph(data.module.channels[0].AnalogInput);
	});
}
 
$(function() {
	checkTemp(); // Gets initial temperature
	setInterval("checkTemp()", 10000); // Sets a 10 Second timer
});

</script> 
</head> 
<body> 

<div id="container"> 
<div id="data_graph"> </div> 
</div> 
</body> 
</html>
</code>
===== Google Chart - Temperature Chart Source Code =====
<code html>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
 
<html xmlns="http://www.w3.org/1999/xhtml"> 
 
<head> 
<title>ioBridge Server Temperature</title> 

<script type="text/javascript" src="https://www.google.com/jsapi"></script> 
<script type="text/javascript"> 
  google.load("jquery", "1");
  google.load("feeds", "1");
</script> 
 
<script type="text/javascript"> 
 
// Globals
var SecondsToSpan = 3600;  //Max of 6400
var PointsToKeep;
var sOffset = 0;
var UpperLimit;

function InitiateChart(){ 
 
   PointsToKeep = SecondsToSpan / 10;  // number of data point to keep in the plot 
 
   my_state.values = [];
   
   checkTemp();
 
   // call for a new data point every 10 seconds
   setInterval('checkTemp()',10000);

}
 
function my_state() { }
 
// This function puts the data into the Array
function storeValue(DataPoint) {
    
    // Update Page
    $("#currentTemp").text(DataPoint);

   DataPoint = Math.round(DataPoint);
     
   my_state.values.push(DataPoint);
 
   // If the plot has been open longer than SecondsToSpan then remove the first data point		
   if (my_state.values.length > PointsToKeep) {     
           
      my_state.values.splice(0,1);
      sOffset = sOffset + 10; 
   }
}
 
function reScale() {
 
  UpperLimit = 0;
 
  // Find the max value in the array
  for (var i = 0; i < my_state.values.length; i++ ) {
      if (my_state.values[i] > UpperLimit){
         UpperLimit = my_state.values[i] * 1.05;
      }
   }
}
 
// Encode the data for google charts
function ioEncode( valueArray ) {
 
   var chartData = [];
 
      for (var i = 0; i < my_state.values.length; i++) {
		
         var currentValue = my_state.values[i] * 100 / UpperLimit;
	     currentValue = Math.round(currentValue);
         
         chartData.push(currentValue);	
      }
	
   var stringTemp = chartData.join(',');
   var newString = "t:" + stringTemp;
   return newString;
}
 
function checkTemp() {
	
	$.getJSON("http://www.iobridge.com/api/module/feed.json?key=zTFNFDol7706vSZnuxel&callback=?",
	function (data) {
        storeValue(data.module.channels[0].AnalogInput); reScale(); updateGraph();
	});
		
}

// This function takes care of formating the URL for google charts and updating the image
function updateGraph() {
 
   var chart_url = "http://chart.apis.google.com/chart?"
   var chart_type = "cht=lc";
   var chartSec = my_state.values.length - 1;  	
 
   chartSec = chartSec * 10 + sOffset;
	
   var chart_size = "&chs=400x350&chtt=ioBridge Server Temperature&chds=0,100&chxt=x,y,x,y&chxl=2:||Time (s)||3:|||Temp||&chxr=1,0," + UpperLimit + "|0," + sOffset + "," + chartSec;
   var chart_data = "&chd=" + ioEncode(my_state.values);
   var url = chart_url + chart_type + chart_size + chart_data;
 	
   var i = $("<img>").attr("src", url);
   $("#data_graph").empty().append(i);
		
}
 
</script>  
</head> 
 
<body onload="InitiateChart()"> 
<div id="container"> 
    <div id="data_graph"> </div>
    
    <p>&nbsp;</p>
    
    <div id="header"> 
	    Current Temperature is <span id="currentTemp"></span>&deg;F<br><br>
	    This chart will automatically add another data point every 10 seconds.   
    </div> 
</div>
</body> 
</html>
</code>

===== Additional Resources =====
  * [[http://www.iobridge.com/ServerTempNeedle.html|ioBridge Server Temperature Needle]]
  * [[http://www.iobridge.com/ServerTempChart.html|ioBridge Server Temperature Chart]]
  * [[http://www.iobridge.com/technology|ioBridge Technology Page]]