Leftronic API Documentation

What is Leftronic?

Leftronic makes powerful dashboards for business intelligence.

• Colorful and interactive data visualizations
• Templates to get you started right away
• Drag-and-drop editor makes it easy for anyone to create a powerful dashboard, customized to their needs
• Integration with Google Analytics, Twitter, Chartbeat, Zendesk, Basecamp, Pivotal Tracker, Facebook, and more to come!
• Dashboards can be protected or shared with a shortened URL
• Powerful API's for Javascript, PHP, Python, Ruby, and Java
• Python Package and Ruby Gem

Technical Notes

We also suggest checking out our API page. While the most detailed documentation is here, it has JSON and CURL examples in addition to a test form to send data to your custom widgets.

Authentication is handled by your API access key. We strongly encourage you to keep this key private. If you're logged in, your key can be found on our API page. If you plan on using one of our API libraries, you will find instructions below on how to set your access key.

All API requests are made by sending a POST request to https://beta.leftronic.com/customSend with a properly formatted JSON packet. We do not support XML.

Current API version is 1.0.

Getting Started

If you haven't already, create an account at https://beta.leftronic.com/accounts/login.

Get your API access key from the API overview page at https://beta.leftronic.com/api.

We recommend checking out our Tutorials to familiarize yourself with your dashboard.

Javascript

Note: Because Javascript is rendered by the browser, your API access key will be clearly visible in plain text. We recommend using our PHP, Python, or Ruby API libraries. If you need to use the Javascript API and have concerns about abuse or misuse of your private key, please feel free to send us an email at [email protected].

Start by downloading the most recent version of our Javascript API at https://github.com/sonofabell/leftronic/blob/master/leftronic.js.

Dependencies

This library uses jQuery for POST requests. Either download jQuery or look at instructions to load from Google's CDN.

<script type="text/javascript" src="your/path/jquery.min.js"></script>

Edit the file, adding your API key here:

var accessKey = "YOUR_ACCESS_KEY";

Add the file to the header of your web pages with the appropriate path linking to the location of your file:

<script type="text/javascript" src="your/path/leftronic.js"></script>

Here are some example functions to push to your dashboard. Be sure you have configured the correct widgets to accept custom data points. Also, be sure that you have entered your API access key correctly.

Let's start with pushing a number to a widget.

pushNumber("yourNumberStream", 14600);

Now we'll push some geographic coordinates to a map widget. You can use either the U.S. or world map widgets. The first coordinate (37.8) is the latitude and the second coordinate (-122.6) is the longitude. If your request is successful, you should see a data point appear on San Francisco, California. Optionally, if you'd like to set the color of your map point simply specify that in your function call. Note: only red, blue, green, purple, and yellow colors are supported at this time. Incorrect or missing color will default to red.

pushGeo("yourGeoStream", 37.8, -122.6);

pushGeo("yourGeoStream", 37.8, -122.6, "blue");

Here's how you push a title and message to a text feed widget.

pushText("yourTextStream", "This is my title.", "Hello World!");

Let's push an array of names and values to a leaderboard widget. Be sure to create the array first (you may call it whatever you'd like). Be careful to use the proper syntax. Next, push the array to your widget.

var leaderArray = [{"name": "Johnny", "value": 84}, {"name": "Jamie", "value": 75}, {"name": "Lance", "value": 62}];

pushLeaderboard("yourBoardStream", leaderArray);

Similar to the last example, let's push a list of items to a list widget. Same rules as last time.

var listArray = [{"listItem": "Elizabeth"}, {"listItem": "Marshall"}, {"listItem": "Claire"}, {"listItem": "Nolan"}];

pushList("yourListStream", listArray);

PHP

Start by downloading the most recent version of our PHP API at https://github.com/sonofabell/leftronic/blob/master/leftronic.php. You only need leftronic.php and the CAcerts folder; the test.html and pushNumber.php are very simple integration examples.

Dependencies

This API library uses "json_encode()" which requires PHP 5.2.0 or greater. Please also make sure to have the CAcerts folder in the same path as your leftronic.php file.

Create a class instance with your API key. Feel free to name it whatever you'd like.

$update = new Leftronic("YOUR_ACCESS_KEY");

Here are some example functions to push to your dashboard. Be sure you have configured the correct widgets to accept custom data points. Also, be sure that you have entered your API access key correctly.

Let's start with pushing a number to a widget.

$update->pushNumber("yourNumberStream", 14600);

Now we'll push some geographic coordinates to a map widget. You can use either the U.S. or world map widgets. The first coordinate (37.8) is the latitude and the second coordinate (-122.6) is the longitude. If your request is successful, you should see a data point appear on San Francisco, California. Optionally, if you'd like to set the color of your map point simply specify that in your function call. Note: only red, blue, green, purple, and yellow colors are supported at this time. Incorrect or missing color will default to red.

$update->pushGeo("yourGeoStream", 37.8, -122.6);

$update->pushGeo("yourGeoStream", 37.8, -122.6, "blue");

Here's how you push a title and message to a text feed widget.

$update->pushText("yourTextStream", "This is my title.", "Hello World!");

Let's push an array of names and values to a leaderboard widget. Be sure to create the array first (you may call it whatever you'd like). Be careful to use the proper syntax. Next, push the array to your widget.

$leaderArray = array(array("name" => "Johnny", "value" => 84), array("name" => "Jamie", "value" => 75), array("name" => "Lance", "value" => 62));

$update->pushLeaderboard("yourBoardStream", $leaderArray);

Similar to the last example, let's push a list of items to a list widget. Same rules as last time.

$listArray = array(array("listItem" => "Elizabeth"), array("listItem" => "Marshall"), array("listItem" => "Claire"), array("listItem" => "Nolan"));

$update->pushList("yourListStream", $listArray);

Python

Note: We also have a Leftronic Python Package that offers the same functionality. You can download it on Github or on the Python Package Index.

Start by downloading the most recent version of our Python API at https://github.com/sonofabell/leftronic/blob/master/leftronic.py.

Dependencies

urllib2 and JSON.

import urllib2
import json

Import the file. Your location may vary.

from leftronic import Leftronic

Create a class instance with your API key. Feel free to name it whatever you'd like.

update = Leftronic("YOUR_ACCESS_KEY")

Here are some example functions to push to your dashboard. Be sure you have configured the correct widgets to accept custom data points. Also, be sure that you have entered your API access key correctly.

Let's start with pushing a number to a widget.

update.pushNumber("yourNumberStream", 14600)

You can also push in a suffix or prefix for a number as follows:

update.pushNumber("yourNumberStream", {"prefix": "$", "number": 4})
update.pushNumber("yourNumberStream", {"suffix": "m/s", "number": 35})

And for sparklines/line graphs, you can use a unix timestamp as follows:

update.pushNumber("yourNumberStream", {"number": 13, "timestamp": 1329205474})

Finally, an array of numbers:

update.pushNumber("yourSparklineStream", [{"number", 93, "timestamp": 1329205474}, {"number": 35, "timestamp": 1329206474}])

For number arrays, timestamps must be monotonically increasing, and each element of the array must have a timestamp.

Now we'll push some geographic coordinates to a map widget. You can use either the U.S. or world map widgets. The first coordinate (37.8) is the latitude and the second coordinate (-122.6) is the longitude. If your request is successful, you should see a data point appear on San Francisco, California. Optionally, if you'd like to set the color of your map point simply specify that in your function call. Note: only red, blue, green, purple, and yellow colors are supported at this time. Incorrect or missing color will default to red.

update.pushGeo("yourGeoStream", 37.8, -122.6)

update.pushGeo("yourGeoStream", 37.8, -122.6, "blue")

You can also push an array of latitude, longitude, and colors:

update.pushGeo("yourGeoStream", [37.8, 12.3], [-122.6, 52], ["blue", "red"])

The above example will create two points. A blue point at (37.8, -122.6) and a red point at (12.3, 52). The color array is optional.

Here's how you push a title and message to a text feed widget:

update.pushText("yourTextStream", "This is my title.", "Hello World!", "http://example.com/myimage.png")

The third parameter, the image URL, is optional.

Let's push an array of names and values to a leaderboard widget. Be sure to create the array first (you may call it whatever you'd like). Be careful to use the proper syntax. Next, push the array to your widget.

leaderArray = [{"name": "Johnny", "value": 84}, {"name": "Jamie", "value": 75}, {"name": "Lance", "value": 62, "prefix": "$"}]

update.pushLeaderboard("yourBoardStream", leaderArray)

Similar to the last example, let's push a list of items to a list widget. Same rules as last time.

listArray = ["Elizabeth", "Marshall", "Claire", "Nolan"]

update.pushList("yourListStream", listArray)

Image and Label widgets are now customizable through the API! Let's update an Image widget:

update.pushImage("yourImageStream", "http://example.com/mypicture.png")

And a Label widget:

update.pushLabel("yourLabelStream", "Uptime")

Updating an X-Y Pair widget:

x = 15
y = 8
update.pushPair("yourPairStream", x, y)

# x and y can also be arrays, such as x = [10, 23, 45], y = [12, 90, 30]
# this would create three points at (10, 12), (23, 90) and (45, 30)

Updating a Table widget:

headerRow = ['name', 'city', 'country']
dataRows = [ ['Lionel', 'Rosario', 'Argentina'], ['Andres', 'Albacete', 'Spain']]
update.pushTable("yourTableStream", headerRow, dataRows)

And clearing a widget. You can programmatically clear Map, Text Feed, Sparkline/Line Graph, and Pair widgets:

update.clear("yourStreamName")

You can also push data to multiple streams in a single call using pushMultiple(data), where data is a list of dicts. For convenience, populate functions, which take the same arguments as their corresponding push functions, can be used to create dicts that are properly formatted for pushMultiple().

multipush = []

multipush.append(update.populateNumber("MyNumberStream", 42))
multipush.append(leftconn.populateGeo("MyMap", 34, -118))

update.pushMultiple(multipush)

Ruby

Note: We also have a Leftronic Ruby Gem that offers the same functionality. You can download it on Github or on RubyGems.

Start by downloading the most recent version of our Ruby API at https://github.com/sonofabell/leftronic/blob/master/leftronic.rb.

Dependencies

RubyGems and JSON. We recommend installing them with the RubyGems installer.

Require the leftronic gem

require 'rubygems'
require 'leftronic'

Create a class instance with your API key. Feel free to name it whatever you'd like.

leftronic = Leftronic.new "YOUR_ACCESS_KEY"

Here are some example functions to push to your dashboard. Be sure you have configured the correct widgets to accept custom data points. Also, be sure that you have entered your API access key correctly.

Let's start with pushing a number to a widget.

update = leftronic.push_number "yourNumberStream", 14600

Now we'll push some geographic coordinates to a map widget. You can use either the U.S. or world map widgets. The first coordinate (37.8) is the latitude and the second coordinate (-122.6) is the longitude. If your request is successful, you should see a data point appear on San Francisco, California. Optionally, if you'd like to set the color of your map point simply specify that in your function call. Note: only red, blue, green, purple, and yellow colors are supported at this time. Incorrect or missing color will default to red.

update = leftronic.push_geo "yourGeoStream", 37.8, -122.6

update = leftronic.push_geo "yourGeoStream", 37.8, -122.6, :blue

Here's how you push a title and message to a text feed widget.

update = leftronic.push_text "yourTextStream", "This is my title.", "Hello World!"

A leaderboard widget requires a hash. The widget will display the hash entries sorted by value.

update = leftronic.push_leaderboard "yourBoardStream", some_hash

update = leftronic.push_leaderboard "yourBoardStream", 'Johnny' => 84, 'Jamie' => 75, 'Lance' => 62

Finally, let's push an array to a list widget.

update = leftronic.push_list "yourListStream", some_array

update = leftronic.push_list "yourListStream", 'Elizabeth', 'Marshall', 'Claire', 'Nolan'

Java

Our Java API was created by Webmetrics and is available at https://github.com/webmetrics/leftronic-java.

At this time we do not offer support for our Java API but we have tested it, and it works.

Feedback and Issues

If you notice any bugs or other issues, submit a patch or send us a pull request. You can also send us an email at [email protected].