Quick-Start Guide for Google Charts API

Google Charts API is a nice, freely available tool for creating really good-looking graphs very painlessly. Don't be fooled by the "API" bit though, there is no need for advanced understanding of HTTP here - you generate most graphs just by adding parameters to a URL! In this post we'll take a look at a few different ways to generate charts.

One-Off Charts

If you just need a beautiful graph to put into a document or post, then the Chart Wizard is the best place to start. You simply choose the type of chart you want, input your data and choose the colours, labels, settings etc, and the wizard generates the URL for you to copy and paste!

The charts are highly configurable and can easily be changed by editing the URL to the image (view the source of this page to see the URL for the chart shown above). This makes it really easy to generate similar-but-different charts in your web applications, by using the wizard and then replacing some relevant parts of it.

Dynamic Charts

As mentioned above, it is very simple to generate charts with Google Charts API - and all the information for generating the chart is on a URL which returns a png file of the resulting chart. This makes it ideal for integrating into our dynamic web applications and charts that are generated are almost overwhelmingly configurable. That said, there are a few key options that will get you started quickly so let's take a quick tour.


Chart Types

There are so many types of chart available, and as well as being scientifically accurate and correct, they are also very pretty! A full selection of line, bar and pie charts are available and can be combined, labelled, stacked and generally perform some tricks I've never mastered with the graph function of my spreadsheet package. Check out the Chart Gallery for an exhaustive selection; I think my personal favourite is the Google-o-meter which I'm increasingly using for dashboard applications.

Whatever type of chart you want to create, all the URLs start with:

http://chart.apis.google.com/chart

Then you start adding information - the chart type is cht so for a line chart, you would pass cht=lc as part of the URL.

Chart Size

This is a required parameter; your chart won't work without the size information being included. You specify the width and height, in pixels, that the resulting image should be, separated by an 'x'. So for an image which is 300px wide and 100px high, our image URL would need to include chs=300x100. Note that the size is the whole image, including titles, labels, legends and so on, so the graph itself may be smaller than this.

Data

On to the important stuff - the data for the chart. This is passed in the chd parameter, and the simplest format is the text format. This format allows you to specify a comma-separated list of values, with each series separated by a pipe. For example, we now have the basic ingredients for a chart showing some data I just invented:

http://chart.apis.google.com/chart?chs=350x180&cht=lc&chd=t:9,6,5,8,3|4,9,7,5,6&chds=0,10,0,10

As you can see, simply listing data points gives us our two data series shown on the graph. The final parameter shown here is chds which defines the scales for the data; we'll talk about axes next.

Axes and Labelling

The Google Charts don't just scale the data and then label the axes; these are actually two entirely separate operations. This is because you can have multiple data series on one graph, with axes on both sides. This makes a very powerful and flexible tool but it does make a simple graph a tiny bit more complicated than I initially expected.

The default is for the Y axis to range from 0 to 100, with the X axis items equally spaced. In the example above I used the chds parameter to change the scale to run from 0 to 10, so my data would display better.

We can add some axis labels too, for both Y axis (numbers) and X axis (days of the week).

http://chart.apis.google.com/chart?chs=350x180&cht=lc&chd=t:9,6,5,8,3|4,9,7,5,6&chds=0,10,0,10
&chxt=x,y&chxl=0:|Mon|Tue|Wed|Thu|Fri&chxr=1,0,10,2

There is quite a lot needed to make this all happen, so let us take one parameter at a time. The first parameter to include is chxt which dictates which axes to display titles for. If you forget this parameter, you will not see any labels so beware! It is possible to add multiple labels to the same axes, and to add labels for the right and top axes if desired. The position of each axis in this list dictates how it is referred to in all the other axis settings. So we have x in position 0 and y in position 1.

To set the labels (i.e. not a numeric scale) for the X axis, we use the chxl parameter. Since the X axis was the first one listed in chxt. we start our line with 0:| and then add our pipe-separated labels.

As soon as you include the Y axis in the chxt list, you will see axis labels, however these will show the default range of 0 to 100! Google Charts handles its axis scales entirely independent from the data scales so this is in fact a feature although at first glance it perhaps isn't the behaviour you might expect. For a numeric scale we use the chxr to specify a range to label, and optionally the interval to use. In the example shown above, we gave the axis index (from the list we gave as the value for chxt), the minumin and maximum values, and the interval to label at.

Colours

As a finishing touch, we can change the colours of our lines to make the graph prettier. Google charts uses hex colours, so this is a pretty easy step. One nice touch is that it also supports an additional two digits on the hex colour, which is the transparency of the colour. Here's the same example with the colours added, using the chco parameter with a list of colours; one for each data series:

http://chart.apis.google.com/chart?chs=350x180&cht=lc&chd=t:9,6,5,8,3|4,9,7,5,6&chds=0,10,0,10&chxt=x,y&chxl=0:|Mon|Tue|Wed|Thu|Fri&chxr=1,0,10,2&chco=3399CCFF,49188F33

Go Forth, and Chart

Hopefully this has shown how easy it is to create a simple yet presentable chart using the Google Charts API. The examples showed a line chart but the same principles apply to all the different chart types - there are some wonderful visual examples in the extensive documentation so do jump in and see what you can make!

If you do start using Google Charts, or are using them already, what are you making? I'd love to see some more examples of the kinds of things they can generate!

4 thoughts on “Quick-Start Guide for Google Charts API

  1. I love the Google charts API. It has saved me from relying on large (and usually buggy) PHP graph libraries in a couple of projects. PHP graph libraries tend to need quite a bit of configuration before data can be displayed, which means it takes a lot of work to you have to move to a different library. With this all you need is a little array to string conversion :)
    One other great thing about Google graphs is that you can use JavaScript to change the source of the graph image and effectively create a dynamically changing graph.

  2. Great post and useful info. I like the api but find it a bit irritating that you can't use https with it. This means it can cause those 'This page contains both secure and unsecure items' warnings whenever you've got it in a secure control panel.

  3. Philip: that's a great point about dynamically changing the graph, hadn't really thought about it that way :)

    David: That is a bit of a downside, do you know if there are any plans to include this?

    • Haven't seen any mention from Google. I noticed that in Magento CE 1.5 they say they're switching to YUI Charts which, from a quick test, seems to support it.

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>