Using Highcharts with awe.sm

Highcharts is a powerful JavaScript and SVG charting library. awe.sm uses Highcharts for its own reports interface. This quick start guide demonstrates how to format awe.sm Stats API intervals for Highcharts.

Formatting data for Highcharts

Highcharts allows for time-delimited data series. This means that instead of passing a series of x and y-axis coordinates, we can simply declare the starting date, the duration of time between each point, and an array of values.

The awe.sm stats/range/intervals endpoint returns an intervals array with an object containing clicks, clicks per share, and shares values for each interval. Reformatting the awe.sm API response into a Highcharts series object can be done easily by extracting the desired stat from each interval object:

// Example awe.sm API response
var awesmResponse = 
{
    "totals": {
        "intervals": [
            {
                "clicks": 4,
                "clicks_per_share": 2,
                "day": "2011-09-01T00:00:00Z",
                "shares": 2
            },
            {
                "clicks": 1,
                "clicks_per_share": 1,
                "day": "2011-09-02T00:00:00Z",
                "shares": 1
            },
            {
                "clicks": 0,
                "clicks_per_share": 0,
                "day": "2011-09-03T00:00:00Z",
                "shares": 0
            }
        ]
    }
}

// Array to hold the Highcharts formatted values
var hcSeriesIntervals = [];

// Extract the desired value from each interval object
for (var i = 0; i < awesmResponse["totals"]["intervals"].length; i++) {
    hcSeriesIntervals.push(awesmResponse["totals"]["intervals"][i]["clicks"]);
}

// hcSeriesIntervals = [4,1,0]

Displaying Clicks

In this example, we'll display the clicks a project received in September 2011.

Step 1: Download Highcharts and include it with jQuery, MooTools, or Prototype.

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>
<script src="highcharts.js"></script>

Step 2: Setup an XHR to the awe.sm stats/range/intervals endpoint.

$.ajax({
    type: "POST",
    url: "http://api.awe.sm/stats/range/intervals.json",
    data: {
        v: 3,
        url: "http://developers.awe.sm/",
        key: "5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9",
        start_date: "2011-09-01",
        end_date: "2011-10-01",
        with_zeros: true
    },
    dataType: "jsonp",
    success: function (awesmResponse) {
        // do something here
    }
});

Step 3: Add the interval reformatting and create a new Highcharts chart.

$.ajax({
    type: "POST",
    url: "http://api.awe.sm/stats/range/intervals.json",
    data: {
        v: 3,
        url: "http://developers.awe.sm/",
        key: "5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9",
        start_date: "2011-09-01",
        end_date: "2011-10-01",
        with_zeros: true
    },
    dataType: "jsonp",
    success: function (awesmResponse) {
        // Reformat awe.sm Stats API output into a Highcharts series
        var hcSeriesIntervals = [];
        
        for (var i = 0, iMax = awesmResponse["totals"]["intervals"].length; i < iMax; i++) {
            hcSeriesIntervals.push(awesmResponse["totals"]["intervals"][i]["clicks"]);
        }
        
        // Create a new Highcharts chart with the reformatted data
        var graph = new Highcharts.Chart({
            chart: {
                renderTo: "graphHolder1",
                defaultSeriesType: "line"
            },
            title : {
                text: "Clicks in September 2011"
            },
            xAxis: {
                type: "datetime",
                title: {
                    text: "Date"
                }
            },
            yAxis: {
                title: {
                    text: "Clicks"
                },
                min: 0
            },
            legend: {
                enabled: false
            },
            series: [{
                name: 'Clicks',
                pointInterval: 24 * 60 * 60 * 1000, // 1 day in milliseconds
                pointStart: Date.UTC(2011, 8, 01),
                data: hcSeriesIntervals
            }]
        });
    }
});

Step 4: Add a div to hold the Highcharts chart.

<div id="graphHolder1"></div>

The result:

Displaying Clicks from Channels

In this example, we'll display the number of clicks each channel received in a stacked area chart.

Like above, include the jQuery and Highcharts libraries. Add <div id="graphHolder2"></div> to hold the Highcharts chart.

The group_by parameter retrieves stats with common values within a parameter. Grouping by channel totals clicks from all links shared within a particular channel. The awe.sm stats/range/intervals endpoint then returns an intervals array for each grouped value. Like the totals array above, the grouped intervals array has a stats object at each interval. Highcharts will need a series object for each grouped value.

$.ajax({
    type: "POST",
    url: "http://api.awe.sm/stats/range/intervals.json",
    data: {
        v: 3,
        url: "http://developers.awe.sm/",
        key: "5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9",
        start_date: "2011-09-01",
        end_date: "2011-10-01",
        group_by: "channel",
        with_zeros: true
    },
    dataType: "jsonp",
    success: function (awesmResponse) {
        console.log('r2', awesmResponse);
        
        // Reformat awe.sm Stats API output into a Highcharts series
        var hcSeries = [];    // Array of series objects to display
        var hcSeriesSetup;   // Temporary object for each series
        
        for (var i = 0, iMax = awesmResponse["groups"].length; i < iMax; i++) {
            // Create a new series
            hcSeriesSetup = {
                name: awesmResponse["groups"][i]["channel"], // The name for this series
                pointInterval: 24 * 60 * 60 * 1000,
                pointStart: Date.UTC(2011, 8, 01),
                data: []
            };
            
            // Add the intervals for this series
            for (var j = 0, jMax = awesmResponse["groups"][i]["intervals"].length; j < jMax; j++) {
                hcSeriesSetup["data"].push(awesmResponse["groups"][i]["intervals"][j]["clicks"]);
            }
            
            // Add this series to the Highcharts array of series objects
            hcSeries.push(hcSeriesSetup);
        }
        
        // Create a new Highcharts chart with the reformatted data
        var graph = new Highcharts.Chart({
            chart: {
                renderTo: "graphHolder2",
                defaultSeriesType: "area"
            },
            title : {
                text: "Clicks per Channel in September 2011"
            },
            xAxis: {
                type: "datetime",
                title: {
                    text: "Date"
                }
            },
            yAxis: {
                title: {
                    text: "Clicks"
                },
                min: 0
            },
            plotOptions: {
                area: {
                    stacking: "normal"
                }
            },
            series: hcSeries
        });
    }
});

The result:

Last updated 2011-10-20

Have questions? Talk to us.

Using Highcharts with awe.sm

Formatting data for Highcharts

Displaying Clicks

Displaying Clicks from Channels