Developer's Guide

The Google Chart API lets you dynamically generate charts. To see the Chart API in action, open up a browser window and copy the following URL into it:

http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=Hello|World

Press the Enter or Return key and - presto! - you should see the following image:

Contents

Audience Usage policy Introduction URL format Required and optional parameters Chart size Chart data Text encoding Text encoding with data scaling Simple encoding Extended encoding Encoding data with JavaScript Guidelines for granularity Chart type Line charts Sparklines Bar charts Pie charts Venn diagrams Scatter plots Radar charts Maps Google-o-meter QR codes New!

Colors Chart colors Solid fill Linear gradient Linear stripes Fill area Labels Chart title Chart legend Extended! Pie chart and Google-o-meter labels Multiple axis labels Styles Bar width and spacing Bar chart zero line Line styles Grid lines Shape and range markers Character mappings Simple encoding character values Extended encoding character values United States of America state codes ISO 3166 Country codes

Back to top

Audience

This document is intended for programmers who want to include Google Chart API images within a webpage. It provides an introduction to using the API and reference material on the available parameters.

Usage Policy

There's no limit to the number of calls per day you can make to the Google Chart API. However, we reserve the right to block any use that we regard as abusive, an apparent denial of service attempt for example. If you think your service will make more than 250,000 API calls per day, please let us know by mailing an estimate to chart-api-notifications@google.com.

Introduction

The Google Chart API returns a PNG-format image in response to a URL. Several types of image can be generated, including line, bar, and pie charts. For each image type you can specify attributes such as size, colors, and labels.

You can include a Chart API image in a webpage by embedding a URL within an <img> tag. When the webpage is displayed in a browser the Chart API renders the image within the page.

All the images in this document were generated with the Chart API. To view the URL of an image :

• if you are using Firefox right-click then select View image or Properties.
• if you are using Internet Explorer right-click then select Properties.

This document describes the required format of Chart API URLs and the available parameters.

Back to top

URL format

Google Chart API URLs must be in the following format:

http://chart.apis.google.com/chart?<parameter 1>&<parameter 2>&<parameter n>

Note: Each URL must be all on one line.

Parameters are separated with the ampersand (&) character. You can specify as many parameters as you like, in any order. For example, the Chart API returns the following chart in response to the URL below:

http://chart.apis.google.com/chart?
chs=250x100
&chd=t:60,40
&cht=p3
&chl=Hello|World

Where:

• http://chart.apis.google.com/chart? is the Chart API's location.
• & separates parameters.
• chs=250x100 is the chart's size in pixels.
• chd=t:60,40 is the chart's data.
• cht=p3 is the chart's type.
• chl=Hello|World is the chart's label.

You can include a Chart API image in an HTML document by embedding a URL within an <img> tag. For example, the following <img> tag results in the same image as above:

<img src="http://chart.apis.google.com/chart?
chs=250x100
&amp;chd=t:60,40
&amp;cht=p3
&amp;chl=Hello|World"
alt="Sample chart" />

Note: When you embed a URL in an HTML <img> tag, take care to use the character entity reference & in place of an ampersand (&).

Back to top

Required and optional parameters

You must provide at least the following parameters:

• Chart size
• Chart data
• Chart type
  

All other parameters are optional. Optional parameters by chart type are listed in the following table. Note that QR Codes are omitted as they have no optional parameters.

Parameter	Bar chart	Line and Sparkline chart	Radar chart	Scatter plot	Venn diagram	Pie chart	Google- o-meter	Maps
Chart colors	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Solid fill	Yes	Yes	Yes	Yes	Yes	Yes	Background only	Background only
Data scaling	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Linear gradient	Yes	Yes	Yes	Yes	Yes	Background only
Linear stripes	Yes	Yes	Yes	Yes	Yes	Background only
Chart title	Yes	Yes	Yes	Yes	Yes	Yes
Chart legend	Yes	Yes	Yes	Yes	Yes
Multiple axis labels	Yes	Yes	Yes	Yes
Grid lines	Yes	Yes	Yes	Yes
Shape markers	Yes	Yes	Yes	Yes
Horizontal range markers	Yes	Yes	Yes	Yes
Vertical range markers	Yes	Yes	Yes	Yes
Line styles	Yes	Yes	Yes
Fill area	Yes	Yes	Yes
Bar width and spacing	Yes
Bar chart zero line	Yes
Pie chart and Google-o-meter labels						Yes	Yes

Back to top

Chart size

Specify chart size with chs=<width in pixels>x<height in pixels>

For example, chs=300x200 generates a chart 300 pixels wide and 200 pixels high.

The largest possible area for all charts except maps is 300,000 pixels. As the maximum height or width is 1000 pixels, examples of maximum sizes are 1000x300, 300x1000, 600x500, 500x600, 800x375, and 375x800.

For maps, the maximum size is 440 pixels wide by 220 pixels high.

Pie charts are clipped (only partially visible) if the size specified is too small. General size guidelines for pie charts are:

• a two-dimensional chart needs to be roughly twice as wide as it is high.
• a three-dimensional chart needs to be roughly two and a half times wider than it is high.

Back to top

Chart data

Before you can create a chart you must encode your data into a form that is understood by the Chart API. Use one of the following formats:

• Text encoding uses a string of positive floating point numbers from zero to one hundred.
  Text encoding with data scaling uses a string of any positive or negative floating point numbers in combination with a scaling parameter. Note this is not available for maps.
  Allowing five pixels per data point, integers (1.0, 2.0, and so on) are sufficient for line and bar charts up to about 500 pixels. Include a single decimal place (35.7 for example) if you require a higher resolution. Text encoding is suitable for all types of chart regardless of size. Note this type of encoding generally results in the longest URL for a given data set.
• Simple encoding uses the alphanumeric characters (A to Z, a to z, and 0 to 9) where A represents 0, B represents 1, and so on up to 9 which represents 61, to provide a resolution of 62 different values.
  Allowing five pixels per data point, this is sufficient for line and bar charts up to about 300 pixels. This type of encoding results in the shortest URL for a given data set.
• Extended encoding uses pairs of alphanumeric characters (plus a few others that are discussed later) where AA represents 0, AB represents 1, and so on up to two periods (..) which represent 4095 to provide a resolution of 4,096 different values.
  Extended encoding is best suited for large charts with a large data range. This type of encoding results in a URL twice the length of simple encoding for a given data set.

Note: For simple and extended encoding you'll most likely want to encode your data programmatically. See the JavaScript snippet for encoding data for a start point. Also, several Chart Group members have contributed API libraries - either trawl the Group or visit the Useful links to API libraries post.

Back to top

Text encoding

Specify text encoding with

chd=t:<chart data string>

Where <chart data string> consists of positive floating point numbers from zero (0.0) to one hundred (100.0), minus one (-1), and the pipe character (|) as a separator.

Note:

• You can specify a missing value with minus one (-1).
• If you have more than one set of data, separate each set with a pipe character (|).

For example: chd=t:10.0,58.0,95.0|30.0,8.0,63.0

Note: For text encoding, scale your data by converting it into percentages of the largest value in your data set.

Back to top

Text encoding with data scaling

Specify text encoding with data scaling with two parameters

chd=t:<chart data string>
chds=<data set 1 minimum value>,<data set 1 maximum value>,<data set n minimum value>,<data set n maximum value>

Where:

• <chart data string> consists of any positive or negative floating point numbers
• <data set 1 minimum value> is the lowest number you want to apply to the first data set
• <data set 1 maximum value> is the highest number you want to apply to the first data set, omit to specify 100
• <data set n minimum value> is the lowest number you want to apply to the nth data set
• <data set n maximum value> is the highest number you want to apply to the nth data set, omit to specify 100

If you supply fewer data scaling parameters than there are data sets the last scaling parameter is applied to the remaining data sets. Provide just one pair of scaling parameters to apply a single range to a chart.

Note:

• This is not available for maps.
• You can specify a missing value with a number that is out of range.
• If you have more than one set of data, separate each set with a pipe character (|).

For example: chd=t:30,-60,50,120,80&chds=-80,140

Back to top

Simple encoding

Specify simple encoding with

chd=s:<chart data string>

Where <chart data string> contains the characters: A to Z, a to z, 0 to 9, underscore (_), and comma (,) as a separator.

Note:

• Upper case A = 0, B = 1 and so on to Z = 25.
• Lower case a = 26, b= 27 and so on to z = 51.
• Zero (0) = 52 and so on to 9 = 61.
• You can specify a missing value with an underscore (_).
• If you have more than one set of data, separate each set with a comma (,).

For example, two sets of data: chd=s:ATb19,Mn5tz where — in the first data set — A represents 0, T represents 19, b represents 27, 1 represents 53, and 9 represents 61.

Note: See Simple encoding character values for a complete listing.

Back to top

Extended encoding

Specify extended encoding with

chd=e:<chart data string>

Where <chart data string> contains pairs of the characters: A to Z, a to z, 0 to 9, hyphen (-), period (.), underscore (_), and comma (,) as a separator.

Note:

• AA = 0, AZ = 25, Aa = 26, Az = 51, A0 = 52, A9 = 61, A- = 62, A. = 63
  BA = 64, BZ = 89, Ba = 90, Bz = 115, B0 = 116, B9 = 125, B- = 126, B. = 127
  .A = 4032, .Z = 4057, .a = 4058, .z = 4083, .0 = 4084, .9 = 4093, .- = 4094, .. = 4095.
• You can specify a missing value with two underscore (__) characters.
• If you have more than one set of data, separate each set with a comma (,).

Note: See Extended encoding character values for instructions on how to generate a complete listing.

Back to top

Encoding data with JavaScript

You will most likely find it easier to translate real-life data into Chart API data programmatically rather than manually.

The following snippet of JavaScript encodes a data set into Simple encoding. The data set must be provided as an array of positive numbers. A data set value that is not a positive number is encoded as a missing value with the underscore character (_).

var simpleEncoding = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
 
function simpleEncode(valueArray,maxValue) {

var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) * currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
return chartData.join('');
}

Call the simpleEncode function passing in the array (valueArray) and the maximum value (maxValue) within that array. In the following example maxValue is set to be larger than the largest number in the array to create some space between the highest value and the top of the chart:

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70; 
simpleEncode(valueArray,maxValue);

Back to top

Guidelines for granularity

Take care not to overestimate the number of data points required for a chart. For example, to show how popular Britney Spears was during the last ten years, aggregating search queries for each day results in more than 3600 values. This would be too much data to pass in a URL, it also would not make any sense to plot a graph at this granularity: on a 1024 pixel wide screen one data point would be about a quarter of a pixel on the screen. The following examples illustrate this point.

200 by 100 chart with 20 data points (10 pixels per data point):

40 data points (5 pixels per data point):

80 data points (only 2.5 pixels per data point):

Back to top

Chart type

The following types of charts are available:

• Line chart
• Sparkline
• Bar chart
• Pie chart
• Venn diagram
• Scatter plot
• Radar chart
• Map
• Google-o-meter

Line charts

Specify a line chart with

cht=<line chart type>

Where <line chart type> is lc or lxy as described in the following table.

• For charts of type lc, multiple data sets are drawn as multiple lines.
• For charts of type lxy a pair of data sets is required for each line.
• For information on how to specify multiple data sets see Chart data.
• For information on available parameters see Optional parameters by chart type.

Parameter	Description	Example
cht=lc	A line chart, data points are spaced evenly along the x-axis.	cht=lc
cht=lxy	Provide a pair of data sets for each line you wish to draw, the first data set of each pair specifies the x-axis coordinates, the second the y-axis coordinates. If you pass in an odd number of data sets the last set is ignored. Provide a single undefined value to evenly space the data points along the x-axis. The example chart uses Text encoding so an undefined value is represented by -1. Simple encoding uses an underscore (_) and Extended encoding two underscores (__) as undefined - or missing - values. Specify data point shape markers with the chm parameter as described in Shape markers. Specify line colors as described in Colors.	cht=lxy chd=t:0,30,60,70,90,95,100| 20,30,40,50,60,70,80| 10,30,40,45,52| 100,90,40,20,10| -1| 5,33,50,55,7

Sparklines

Specify a sparkline with

cht=ls

A sparkline chart has exactly the same parameters as a line chart. The only difference is that the axis lines are not drawn for sparklines by default. You can add axis labels if you wish, see Multiple axis labels for more information.

Back to top

Bar charts

Specify a bar chart with

cht=<bar chart type>

Where <bar chart type> is bhs, bhg, bvs or bvg as described in the following table.

• Depending on the bar chart type, multiple data sets are drawn as stacked or grouped bars.
• For information on how to specify multiple data sets see Chart data.
• For information on available parameters see Optional parameters by chart type.

Parameter	Description	Example
cht=bhs cht=bvs	Horizontal and vertical bar chart respectively. The first example (all bars in dark blue) has a single data set. The second example (bars in dark and pale blue) has two data set. As you can see, multiple data sets are stacked so you must specify a color for each data set. You can also specify a color for each data point within a single data set. See Colors for details. The second example does not use data scaling so data points that have a combined value greater than 100 are off the scale. The third example does use data scaling so the bars are scaled correctly.	cht=bhs chco=4d89f9 cht=bvs chco=4d89f9,c6d9fd chd=t:10,50,60,80,40| 50,60,100,40,20 cht=bvs chco=4d89f9,c6d9fd chd=t:10,50,60,80,40| 50,60,100,40,20 chds=0,160
cht=bhg cht=bvg	Horizontal and vertical bar chart, respectively, in specified colors; multiple data sets are grouped.	cht=bhg chco=4d89f9,c6d9fd cht=bvg chco=4d89f9,c6d9fd
chbh	Bar chart size is handled in a different way than for other chart types. For horizontal bar charts of type bhs and bhg, and for vertical bar charts of type bvs and bvg, chart size is determined by the chs parameter. The chart is clipped (only partially visible) if the size specified (with chs) is too small.  Because of this you may wish to specify bar width and spacing with chbh= <bar width in pixels>, <optional space between bars in a group>, <optional space between groups> Note: if the third parameter (space between bars) is not supplied, this defaults to half the value of space between groups.	chbh omitted cht=bhs chbh=10 cht=bhs

Back to top

Pie charts

Specify a pie chart with

cht=<pie chart type>

Where <pie chart type> is p or p3 as described in the following table.

• Supply one data set only; subsequent data sets are ignored.
• For information on available parameters see Optional parameters by chart type.

Note: The Google Chart API calculates the circle's radius from the minimum of width and height specified in the chart size (chs) parameters. The chart is clipped if the size specified is too small. If you are including labels you probably need to specify the width to be twice the height.

Parameter	Description	Example
cht=p	Two dimensional pie chart. Unless specified otherwise, pie segment colors are interpolated from dark orange to pale yellow. Specify other colors as described in Colors. Specify labels with chl as described in Pie chart labels.	cht=p chs=200x100
cht=p3	Three dimensional pie chart. Specify labels with chl as described in Pie chart labels.	cht=p3 chs=250x100

Back to top

Venn diagrams

Specify a venn diagram with

cht=v

Supply one data set where:

• the first three values specify the relative sizes of three circles, A, B, and C
• the fourth value specifies the area of A intersecting B
• the fifth value specifies the area of A intersecting C
• the sixth value specifies the area of B intersecting C
• the seventh value specifies the area of A intersecting B intersecting C

Parameter	Description	Example
cht=v	In this example the first circle is specified with 100, the second with 80, and the third with 60. The overlap between all circles is specified with 30. For information on available parameters for Venn diagrams see Optional parameters by chart type.	cht=v chd=t:100,80,60,30,30,30,10

Back to top

Scatter plots

Specify a scatter plot with

cht=s

• Scatter plots use multiple data sets differently than other chart types. You can only show one data set in a scatter plot. Though you use three data sets to specify each point's x position, y position, and optionally size. For information on how to specify multiple data sets see Chart data.
• For information on available parameters see Optional parameters by chart type.

Parameter	Description	Example
cht=s	Supply two data sets: the first data set specifies x coordinates, the second set specifies y coordinates. The default shape for data points is a circle. Specify a different data point shape with the chm parameter as described in Shape markers. The default data point color is blue. Specify other colors as described in Colors. In the example, you'll notice the data points vary in size. To do this, specify a third data set. Any size specified with the chm parameter determines the maximum size for any data point. The size at which each data point is drawn is scaled with the optional third data set. So, for example, specifying a size of 20 pixels with chm and the highest value possible for the type of encoding you are using (9, 100.0 or ..) in the third data set will result in a data point of 20 pixels.	cht=s

Back to top

Radar charts

Specify a radar chart with

cht=r or cht=rs

For a chart of type r points are connected with straight lines.

For a chart of type rs points are connected with splines to form a curved line.

• Multiple data sets are drawn as multiple lines.
• For information on how to specify multiple data sets see Chart data.
• For information on available parameters see Optional parameters by chart type.

Parameter	Description	Example
cht=r	In a radar chart, data points are drawn between the center of the chart and the perimeter. Points of value zero (0, A or AA depending on the type of encoding) are drawn at the center while those with the maximum value for the encoding used (100, 9 or ..) are drawn at the perimeter. Intermediate values are scaled between the two. The points representing the first and last values in the data set are drawn between the center of the chart and the top of the chart. The remaining points are evenly spaced traveling clockwise around the chart, and, in this type of radar chart, a straight line is drawn between each pair of points. This example shows a simple radar chart, with a single data set.	cht=r chd=t:10,20,30,40,50,60,70,80,90
	You can add further information and clarity to a radar chart by adding colors, line styles, and axis labels. This example is a more complex radar chart with two data sets. The color of each data set is specified with chco, as described in Chart colors. Line styles are specified with chls, as described in Line styles. Finally axis labels are specified with chxt, chxl, and chxr - see Multiple axis labels for more information. For radar charts the x-axis is drawn in a circle, while the y and r axes go from the center of the chart to the top. The t axis is ignored. Note: When labels are included, the spacing of the data points around the chart is determined by either the number of labels or the number of data points minus one, whichever is the larger.	chco=FF0000,FF9900 chls=2.0,4.0,0.0|2.0,4.0,0.0 chxt=x chxl=0:|0|45|90|135|180|225|270|315 chxr=0,0.0,360.0
	This example uses the same parameters as the previous example, but has a Fill area specified for both data sets. It also has an added grid. See Grid lines for more information.	chg=25.0,25.0,4.0,4.0 chm= B,FF000080,0,1.0,5.0| B,FF990080,1,1.0,5.0
	The final example shows the previous example with added Shape markers. Note that the horizontal line shape marker (specified with chm=h) produces a circle on a radar chart, while vertical lines (chm=v and chm=V) are drawn from the center of the chart to the perimeter. the outer blue circle is specified with chm=h,0000FF,... the inner, partially transparent, blue circle is specified with chm=h,3366CC80,... the partially transparent green line (between 1 and 2 o'clock) is specified with chm=V,00FF0080,... the dark green line (at 8 o'clock) is specified with chm=V,008000,... the green line (at 10 o'clock) is specified with chm=v,00A000,... See Shape markers and Colors for information. You can also specify range markers, see Range markers for more information.	chm= h,0000FF,0,1.0,4.0| h,3366CC80,0,0.5,5.0| V,00FF0080,0,1.0,5.0| V,008000,0,5.5,5.0| v,00A000,0,6.5,4

Back to top

Maps

Specify a map with

cht=t and chtm=<geographical area>

Where <geographical area> is one of the following:

• africa
• asia
• europe
• middle_east
• south_america
• usa
• world

For example:

chs=440x220
chd=s:_
cht=t
chtm=world

Note: Text encoding with data scaling is not available for maps. Instead use text encoding, simple encoding or extended encoding.

This is the default map for the world. The size used in the example (440 by 220 pixels) is the maximum available for all maps. Also notice the data set contains just one character, an underscore (_). This specifies a missing value in simple encoding and gives us the simplest map possible. You can make your map much more informative - and interesting - than the above example by using color for one or more countries on the map.

Specify the colors on a map, and how they are applied to each country or state within the map, with three parameters in combination:

chco=<default color><colors for gradient>
chld=<list of codes for each country or state to be colored>
chd=<list of values for each country or state to be colored>

Where:

• <default color>, <colors for gradient> are RRGGBB format hexadecimal numbers. The default color is applied to countries or states that are not listed in the chld parameter. The other colors specify the extremes of a color gradient that is used to color all countries listed in the chld parameter. The color that is applied depends on the country's value in the chd parameter.
• <list of codes for each country or state to be colored> is a list of either:
  • ISO 3166-1-alpha-2 codes for countries as defined by ISO3166, see ISO 3166 Country codes.
  • USA state codes as listed in United States of America state codes.
• <list of values for each country or state to be colored> are simple, text or extended encoding values. The first value is used for the first country listed in the chld parameter, the second for the second and so on. The lowest data value; A, 0, or AA depending on the type of encoding used, is drawn in the color specified by <color for start of gradient> in chco. The highest; 9, 100, or .. is drawn in the color specified by <color for end of gradient>. Intermediate values give intermediate colors.

For example:

chtm=africa
chco=ffffff,edf0d4,13390a
chld=MGKETN
chd=s:Af9
chf=bg,s,EAF7FE

In this example:

• the first color (ffffff which specifies white) is used for any country not listed in the chld parameter
• the second and third colors specify a color gradient from pale green (edf0d4) to dark green (13390a)
  
• the countries to be colored are Madagascar (MG), Kenya (KE), and Tunisia (TN)
• Madagascar has a value of A which is the the minimum value possible in simple encoding and equates to zero.
  Madagascar is therefore drawn in pale green (edf0d4)
• Kenya has a value of f which equates to 31. Kenya is therefore drawn in a color intermediate between pale and dark green
• Tunisia has a value of 9 which is the the maximum value possible in simple encoding and equates to 61.
  Tunisia is therefore drawn in dark green (13390a)
• water masses are colored pale blue (EAF7FE) as these are considered to be the map's background. See the chf parameter as described in Chart area and background fill.

Here's a more colorful example:

chco=
f5f5f5,
edf0d4,
6c9642,
13390a

Here the default color is f5f5f5. The color gradient is specified with edf0d4, 6c9642, and 13390a. It's easiest to explain how this is applied using text encoding:

• a value of zero is drawn in the palest green (edf0d4)
• a value of 50 is drawn in mid green (6c9642)
• a value of 100 is drawn in the darkest green (13390a)
• a value in between these numbers is interpolated between the nearest colors. So, for example, a value of 75 is halfway between the mid green (6c9642) and the darkest green (13390a).

Back to top

Google-o-meter

Specify a Google-o-meter with

cht=gom

For information on available parameters see Optional parameters by chart type.

Parameter	Description	Example
cht=gom	Here's an example of a Google-o-meter using the default colors (red on the left shading through orange and yellow to green on the right). See Chart colors for information on specifying other colors. See Pie chart and Google-o-meter labels for information on specifying the text that appears at the end of the arrow.	cht=gom chd=t:70

Back to top

QR codes

QR Codes are a popular type of two-dimensional barcode, which are also known as hardlinks or physical world hyperlinks. QR Codes store text which can be a hyperlink, contact information, telephone number, even whole verses of poems!

To the human eye QR Codes look like hieroglyphics, but they can be read by any device that has the appropriate software installed. Such devices range from dedicated readers to mobile phones. So, a person with a suitable mobile device can scan a QR code, on a magazine say, which causes the phone's browser to launch to the URL in the QR code.

Specify a QR code with

cht=qr
chl=<text to encode>
choe=<output encoding>

where:

• <text to encode> is text for the QR code. This must be url-encoded in UTF8. Note the space between hello and world is written as %20 in the following example.
• <output encoding> optionally specifies how the output is encoded. If this is not specified the default of UTF-8 is used. Available options are: Shift_JIS, UTF-8, or ISO-8859-1.

For example:

cht=qr
chl=hello%20world
choe=UTF-8

At 21 rows by 21 columns the example QR code above is the simplest possible and is known as version 1:

• Version 1 has 21 rows and columns and can encode up to 25 alphanumeric characters
• Version 2 has 25 rows and columns and can encode up to 47 alphanumeric characters
• Version 3 has 29 rows and columns and can encode up to 77 alphanumeric characters
• ...
• Version 40 has 177 rows and columns and can encode up to 4,296 alphanumeric characters

The Chart API generates the appropriate QR code version depending on the number of characters you provide. For example, if you provide 55 alphanumeric characters the Chart API will generate a version 3 QR code. This is modified by the error correction (EC) level you choose to use, more on EC levels in the following section.

Note: It's easy here to confuse number of rows and columns with QR code size. The number of characters you provide determines the number of rows and columns. The pixel size of the chart is determined with chs as usual (see Chart size).

Error correction and margins

Four levels of EC are available. The default level (L) allows the QR code to be read even if up to 7% of the code is misread, missing or obscured. Other levels provide greater EC levels. The number of characters that can be encoded decreases with increasing EC level. See Versions, error correction and maximum characters for details.

The default margin is 4 modules. This means a blank space equivalent to four rows at the top and bottom and four columns on the left and right are placed around the QR code. This is the minimum required by QR readers.

Optionally, specify an EC level and margin with

chld=<EC level>|<margin>

Where:

• <EC level> is one of
  - L allows 7% of a QR code to be restored
  - M allows 15% of a QR code to be restored
  - Q allows 25% of a QR code to be restored
  - H allows 30% of a QR code to be restored
  (or their lower case equivalents l, m, q, or h).
• <margin> defines the margin (or blank space) around the QR code. The default image has a margin equivalent to 4 rows / columns of the chart.
  

Versions, error correction and maximum characters

Before generating your QR code consider what kind of device will be used to read your code. The best QR code readers will be able to read version 40 codes, mobile devices may read only up to version 4.

We recommend you stick to version 4, which equates to about 100 alphanumeric characters at the default EC level.

See the following table for information on maximum characters for each version and EC level.

Version	Rows by columns	EC level	Maximum characters by EC level and character type
			Digits: 0 to 9	Alphanumeric: 0 to 9, A to Z, space, $ % * + - . / :	Binary	Kanji
1	21x21	L	41	25	17	10
		M	34	20	14	8
		Q	27	16	11	7
		H	17	10	7	4
2	25x25	L	77	47	32	20
		M	63	38	26	16
		Q	48	29	20	12
		H	34	20	14	8
3	29x29	L	127	77	53	32
		M	101	61	42	26
		Q	77	47	32	20
		H	58	35	24	15
4	33x33	L	187	114	78	48
		M	149	90	62	38
		Q	111	67	46	28
		H	82	50	34	21
10	57x57	L	652	395	271	167
		M	513	311	213	131
		Q	364	221	151	93
		H	288	174	119	74
40	177x177	L	7,089	4,296	2,953	1,817
		M	5,596	3,391	2,331	1,435
		Q	3,993	2,420	1,663	1,024
		H	3,057	1,852	1,273	784

Further information and standards

QR code is trademarked by Denso Wave, inc. As you'd expect, the Denso Wave website includes a lot of useful information about QR codes.

QR code was approved as:

• AIM International (Automatic Identification Manufacturers International) standard (ISS - QR Code) in October 1997.
• JEIDA (Japanese Electronic Industry Development Association) standard (JEIDA-55) in March 1998.
• JIS (Japanese Industrial Standards) standard (JIS X 0510) in January 1999.
• ISO international standard (ISO/IEC18004) in June 2000.

QR code reader software is available from many sources. Google offers a QR Code reader library, Zebra Crossing (ZXing), for free. See http://code.google.com/p/zxing/ for details.

See Barcode Contents for a rough guide to standard encoding of information in barcodes.

Back to top

Colors

Specify a color with at least a 6-letter string of hexadecimal values in the format RRGGBB. For example:

• FF0000 = red
• 00FF00 = green
• 0000FF = blue
• 000000 = black
• FFFFFF = white

You can optionally specify transparency by appending a hexadecimal value between 00 and FF where 00 is completely transparent and FF completely opaque. For example:

• 0000FFFF = solid blue
• 0000FF00 = transparent blue
  

The following color options are available:

• Chart colors
• Solid fill Extended!
• Linear gradient
• Linear stripes
• Fill area

Back to top

Chart colors

Specify colors for lines, bars, Venn diagrams, Google-o-meters, and pie segments with

chco=
<color1>,
...
<colorn>

Where <color1> and all subsequent color values are RRGGBB format hexadecimal numbers.

Parameter	Description	Example
chco	This example has three data sets and three colors specified.	chco=ff0000,00ff00,0000ff
	This example also has three data sets, but only two colors are specified. Because of this the last two lines are both drawn in the last color (red ff0000).	chco=ff0000,0000ff
	For bar charts, if the number of colors specified is less than the number of data sets then colors are alternated. In the following chart, the third data set, Bar, is drawn in the first color. If only one color is specified all data sets are drawn in that color.	chco=ff0000,00ff00 chd=s:FOE,THE,Bar
	Here's the same chart with three colors specified.	chco=ff0000,00ff00,0000ff chd=s:FOE,THE,Bar
	Specify a color for each data point within a single data set by separating chco color parameters with the pipe character (|) .	chco=ff0000|00ff00|0000ff chd=s:elo
	For pie charts, if the number of colors specified is less than the number of slices, then colors are interpolated.	chco=0000ff
	For Venn diagrams, if the number of colors specified is less than the number of circles the last color specified is repeated.	chco=00ff00,0000ff
	For Google-o-meters specify at least two colors, more if you want to specify the gradient in between.	chco=ffffff,ffaaaa,ff0000

Back to top

Fill area

Specify a fill area with

chm=
b,<color>,<start line index>,<end line index>,<any value>|
...
b,<color>,<start line index>,<end line index>,<any value>

Where:

• <color> is an RRGGBB format hexadecimal number.
• <start line index> is the index of the line at which the fill starts. This is determined by the order in which data sets are specified with chd. The first data set specified has an index of zero (0), the second 1, and so on.
• <end line index> is the index of the line at which the fill ends. This is determined by the order in which data sets are specified with chd. The first data set specified has an index of zero (0), the second 1, and so on.
• <any value> is ignored.

Separate multiple fill areas with the pipe character (|).

Parameter	Description	Example
chm=b	Take care to specify the data set with the largest values first: To fill from the top of the chart to the first line include a data set with only the highest data value (9, 100.0, or .. depending on the type of encoding used). To fill from the last line to the bottom of the chart include a data set with only the lowest data value (A, 0, or AA depending on the type of encoding used). The lines themselves are drawn in black using chco as described in Colors.	chd=s: 99, cefhjkqwrlgYcfgc, QSSVXXdkfZUMRTUQ, HJJMOOUbVPKDHKLH, AA chm= b,76A4FB,0,1,0| (light blue) b,224499,1,2,0| (blue) b,FF0000,2,3,0| (red) b,80C65A,3,4,0 (green) chco=000000,000000,000000, 000000,000000
	By contrast the first and last data sets (99 and AA) have been removed for this chart. Also, chco is omitted so lines are drawn according to the chart type parameter. Here the parameter is cht=lc so the default line color of yellow is used.	chd=s: cefhjkqwrlgYcfgc, QSSVXXdkfZUMRTUQ, HJJMOOUbVPKDHKLH, chm= b,224499,0,1,0| (blue) b,FF0000,1,2,0| (red) b,80C65A,2,3,0 (green)
chm=B	For a single data set, it is simpler to use chm=B. In this case all the area under the line is filled. Note that chm=b does not work on a radar chart, though you can use chm=B.	chm=B,76A4FB,0,0,0 chd=s:ATSTaVd21981uocA

Back to top

Solid fill

Specify solid fill with

chf=
<bg or c or a>,s,<color>|
<bg or c or a>,s,<color>

Where:

• <bg or c or a> is:
  - bg for background fill
  - c for chart area fill
  - a to apply transparency to the whole chart.
• <s> indicates solid fill.
• <color> is an RRGGBB format hexadecimal number.
• the pipe character (|) separates fill definitions. No pipe character is required after the second definition.

You can specify:

• background, chart area fill, and transparency for line charts, sparklines, and scatter plots.
• background fill and transparency for bar charts, pie charts, and Venn diagrams.
• background fill for maps and radar charts.

Parameter	Description	Example
chf	This example fills the image background with pale gray (efefef).	chf=bg,s,efefef
	This example fills the background with pale gray (efefef) and chart area in black (000000).	chf=bg,s,efefef| c,s,000000
	Note the effect of specifying transparency using the hexadecimal values of 20 for the background and 80 for the chart area.	chf=bg,s,efefef20| c,s,00000080
	This example applies transparency to the whole chart.	chf=a,s,efefeff0

Back to top

Linear gradient

Specify linear gradient for line charts, sparklines, bar charts, Venn diagrams, radar charts and scatter plots with

chf=<bg or c>,lg,<angle>,<color 1>,<offset 1>,<color n>,<offset n>

Where:

• <bg or c> is bg for background fill or c for chart area fill.
• lg specifies linear gradient.
• <angle> specifies the angle of the gradient between 0 (horizontal) and 90 (vertical).
• <color x> are RRGGBB format hexadecimal numbers.
• <offset x> specify at what point the color is pure where: 0 specifies the right-most chart position and 1 the left-most.

Parameter	Description	Example
chf	Chart area has a horizontal (left to right) linear gradient, specified with an angle of zero degrees (0). Blue (76A4FB) is the first color specified. This is pure at the right-most side of the chart. White (ffffff) is the second color specified. This is pure at the left-most side of the chart. The chart background is drawn in gray (EFEFEF).	chf= c,lg,0,76A4FB,1,ffffff,0| bg,s,EFEFEF
	Chart area has a diagonal (bottom left to top right) linear gradient, specified with an angle of forty five degrees (45). White (ffffff) is the first color specified. This is pure at the bottom left of the chart. Blue (6A4FB) is the second color specified. This is pure at the top right of the chart. The chart background is again drawn in gray (EFEFEF).	chf= c,lg,45,ffffff,0,76A4FB,0.75| bg,s,EFEFEF
	Chart area has a vertical (top to bottom) linear gradient, specified with an angle of ninety degrees (90). Blue (76A4FB) is the first color specified. This is pure at the top of the chart. White (ffffff) is the second color specified. This is pure at the bottom of the chart. The chart background is again drawn in gray (EFEFEF).	chf= c,lg,90,76A4FB,0.5,ffffff,0| bg,s,EFEFEF

Back to top

Linear stripes

Specify linear stripes for line charts, sparklines, bar charts, Venn diagrams, radar charts and scatter plots with

chf=<bg or c>,ls,<angle>,<color 1>,<width 1>,<color n>,<width n>

Where:

• <bg or c> is bg for background fill or c for chart area fill.
• ls specifies linear stripes.
• <angle> specifies the angle of the gradient between 0 (vertical) and 90 (horizontal).
• <color> is an RRGGBB format hexadecimal number.
• <width> must be between 0 and 1 where 1 is the full width of the chart. Stripes are repeated until the chart is filled.

Parameter	Description	Example
chf	Chart area with vertical stripes specified with an angle of zero (0). The first color specified (dark gray CCCCCC) is the first stripe drawn at a width of 20% of the chart width. The second color specified (white ffffff) is also drawn at a width of 20%. Stripes alternate until the chart is filled. The chart background is omitted.	chf=c,ls,0,CCCCCC,0.2, FFFFFF,0.2
	Chart area with horizontal stripes specified with an angle of ninety degrees (90). The first color specified (the darkest gray 999999) is the first stripe drawn at a width of 25% of the chart width. The second and third colors specified (the lighter gray CCCCCC and white FFFFFF) are also drawn at a width of 25%. Stripes alternate until the chart is filled. The chart background is omitted.	chf= c,ls,90, 999999,0.25, CCCCCC,0.25, FFFFFF,0.25

Back to top

Labels

The following types of labels are available:

• Chart title
• Chart legend
• Pie chart labels
• Multiple axis labels

Chart title

Specify a chart title with

chtt=<chart title>

Parameter	Description	Example
chtt	Specify a space with a plus sign (+). Use a pipe character (|) to force a line break.	chtt=Site+visitors+by+month| January+to+July
	Optionally, you can also set the title's color and size with chts=<color>,<fontsize> The chart is clipped (only partially visible) if the size specified (with chs) is too small.	chtt=Site+visitors chts=FF0000,20

Back to top

Legend

Specify a legend with

chdl=<first data set label>|<n data set label>

Parameter	Description	Example
chdl	Use chdl together with line colors as described in Colors. In these examples the first data set is drawn in red, the second in green and the third in blue.	chdl=NASDAQ|FTSE100|DOW chco=ff0000,00ff00,0000ff
		chdl=First|Second|Third chco=ff0000,00ff00,0000ff
chdl and chdlp	Use chdl together with the chdlp parameter to specify the legend's position as follows: chdlp=b places the legend at the bottom chdlp=t places the legend at the top chdlp=r places the legend on the right chdlp=l places the legend on the left	chdl=First|Second|Third chco=ff0000,00ff00,0000ff chdlp=l

Back to top

Pie chart and Google-o-meter labels

For a pie chart specify labels with

chl=
<label 1 value>|
...
<label n value>

You can specify a missing value with two consecutive pipe characters (||).

Note: To display labels:
- A two-dimensional chart needs to be roughly twice as wide as it is high.
- A three-dimensional chart needs to be roughly two and a half times wider than it is high.

For a Google-o-meter specify the text that appears above the arrow with

chl=<label>

Parameter	Description	Example
chl	Labels for a three-dimensional pie chart.	chl=May|Jun|Jul|Aug|Sep|Oct chs=220x100
	A good rule of thumb is provided above for how wide you need to make a pie chart to include labels - however, don't forget that you still need to take into account how long your labels are! Here the labels are only partially displayed as the chart is not wide enough.	chl=May|June|July|August| September|October chs=220x100
	This chart needs a width of 280 pixels to display the labels in full.	chl=May|June|July|August| September|October chs=280x100
	Here's an example of a Google-o-meter with a label.	chl=Hello

Back to top

Multiple axis labels

Multiple axis labels are available for line charts, bar charts, radar charts, and scatter plots:

• Axis type
• Axis labels
• Axis label positions
• Axis range
• Axis styles

Axis type

Specify multiple axes with

chxt=
<axis 1>,
...
<axis n>

Available axes are:

• x = bottom x-axis
• t = top x-axis
• y = left y-axis
• r = right y-axis

Axes are specified by the index they have in the chxt parameter specification. The first axis has an index of 0, the second has an index of 1, and so on. You can specify multiple axes by including x, t, y, or r multiple times.

To create multiple axes at least the chxt parameter is required. If other parameters are missing the Chart API uses defaults as described in the following sections.

Parameter	Description	Example
chxt	These examples show two lower x-axes (x is included twice), left and right y-axes (y and r) plus one top axis (t). Because axis labels are omitted the Chart API assumes a range of 0 to 100 for all axes in the line chart. 0 to 100 for the y- and r-axes on the vertical bar chart, but centres the x- and t-axis labels underneath each of the bars and labels them 0 through 4. 0 to 100 for both x-axes and the t-axis on the horizontal bar chart, but centres the y- and r-axis labels next to each of the bars and labels them with the axis index (0 through 4). Also, the height of the horizontal chart needs to be increased else the chart is clipped. Note: For the sake of brevity vertical, but not horizontal, bar charts are discussed in the remainder of this section. The behaviour of the y- and r-axes in a horizontal bar chart is the same as the x- and t-axes in a vertical bar chart.	chxt=x,y,r,x,t

Back to top

Axis labels

Specify labels with

chxl=
<axis index>:|<label 1>|<label n>|
...
<axis index>:|<label 1>|<label n>

The index parameter specifies the index of the axis to which the labels apply.
All labels are separated by the pipe character (|).

Note: Axis labels must be specified in sequence (0, then 1, then 2, and so on).

The first label is placed at the start, the last at the end, others are uniformly spaced in between.

Parameter	Description	Example
chxt and chxl	These examples show left and right y-axes (y and r) plus two sets of values for the x-axis (x). Note: Bar chart x-axis labels are centred beneath each bar. Because of this, unlike in the line chart, the year is specified for each bar in the bar chart.	chxt=x,y,r,x chxl= 0:|Jan|July|Jan|July|Jan| 1:|0|100| 2:|A|B|C| 3:|2005|2006|2007 As above for the line chart except: 3:|2005|2005|2006|2006|2007
	As above except y-axis labels (index 1) are not specified	chxt=x,y,r,x chxl= 0:|Jan|July|Jan|July|Jan| (y-axis omitted) 2:|A|B|C| 3:|2005|2006|2007 As above for the line chart except: 3:|2005|2005|2006|2006|2007

Back to top

Axis label positions

Specify label positions with

chxp=
<axis index>,<label 1 position>,<label n position>|

...
<axis index>,<label 1 position>,<label n position>

Use floating point numbers for position values. Separate data for a different axis with a pipe character (|). If labels (chxl) are omitted, label text is taken from the position value.

Parameter	Description	Example
chxp	This example shows left and right y-axes (y and r) and one x-axis (x). The x-axis (index 0) has neither positions nor labels so the Chart API assumes a range of 0 to 100 and spaces the values evenly. The left y-axis (index 1) has both labels (max, average, and min) and positions (10,35,75). The r-axis (index 2) has only positions (0,1,2,4) so the Chart API uses the positions as the labels. A range is specified for this axis, chxr=2,0,4, see the next section for details.	chxt=x,y,r chxl=1:|min|average|max chxp=1,10,35,75|2,0,1,2,4 chxr=2,0,4
	This example shows left and right y-axes (y and r) and two x-axes (x). Similar to the example above, except the positions of labels for two x-axes are specified. This illustrates that you can overide the Chart API's positioning of labels for a bar chart by using chxp.	chxt=x,y,r,x chxr=2,0,4|3,0,4 chxl=1:|min|average|max chxp=0,10,35,75     |1,10,35,75     |2,0,1,2,4     |3,0,1,2,4

Back to top

Axis range

Specify a range with

chxr=
<axis index>,<start of range>,<end of range>|
...
<axis index>,<start of range>,<end of range>

Separate multiple axis ranges with the pipe character (|).

Parameter	Description	Example
chxr	This example shows left and right y-axes (y and r) and one x-axis (x). Each axis has a defined range. Because no labels or positions are specified, values are evenly spaced and taken from the given range. In the bar chart, note that again the x-axis is handled differently, each bar is given a label. Note: Axis direction is reversed for the r-axis (index 2) as the first value (1000) is larger than the last value (0).	chxt=x,y,r chxr=0,100,500| 1,0,200| 2,1000,0
	Here only the x-axis is defined (x). This axis has range, labels, and positions so all three sets of values are used.	chxt=x chxr=0,100,500 chxl=0:|200|300|400 chxp=0,200,300,400

Back to top

Axis styles

Specify font size, color, and alignment for axis labels with

chxs=
<axis index>,<color>,<font size>,<alignment>|
...
<axis index>,<color>,<font size>,<alignment>

where:

• <axis index> is the axis index as specified in chxt.
• <color> is an RRGGBB format hexadecimal number.
• <font size> is optional. If used this specifies the size in pixels.
• <alignment> is optional. By default: x-axis labels are centered, left y-axis labels are right aligned, right y-axis labels are left aligned. To specify alignment, use 0 for centered, -1 for left aligned, and 1 for right aligned.

Separate multiple values with a pipe character (|).

Parameter	Description	Example
chxs	Font size, color, and alignment are specified for the second x-axis.	chxt=x,y,r,x chxr=2,0,4 chxl=3:|Jan|Feb|Mar|1:|min|average|max chxp=1,10,35,75 chxs=3,0000dd,13
	Font size, color, and alignment are specified for both x-axes.	chxt=x,y,r,x chxl=3:|Jan|Feb|Mar||      0:|1st|15th|1st|15th|1st chxs=0,0000dd,10|3,0000dd,12,1

Back to top

Styles

The following styles are available:

• Bar width and spacing
• Bar chart zero line
• Line styles
• Grid lines
• Shape markers
• Horizontal range markers
• Vertical range markers

Bar width and spacing

For bar charts, specify bar thickness and spacing with
chbh=
<bar width in pixels>,
<optional space between bars in a group>,
<optional space between groups>

Parameter	Description	Example
chbh	In the first example, bar width is set to 10 pixels, space between bars defaults to 4 pixels, and the space between groups defaults to 8 pixels. In the second example, bar width is set to 10 pixels, space between bars is 5 pixels, and the space between groups is 15 pixels. Take care if you provide only two values. In the third example space between bars is set to 8 pixels. As this is the default value for space between groups the visual distinction is completely lost. Specifying a value greater than 8 is even worse - the wrong bars appear to be grouped together.	cht=bhg chbh=10 cht=bvg chbh=10,5,15 cht=bhg chbh=10,8 cht=bhg chbh=10,15

Back to top

Bar chart zero line

For bar charts, specify a zero line with

chp=
<value between 0 and 1 for dataset 1>,
<value between 0 and 1 for dataset n>

Provide just one value to apply the same zero line to all data sets.

Parameter	Description	Example
chp	In this example, a chp value of .5 places the zero line half way up the chart. This chart uses text encoding so a data point with a value of: 0 to 49 is drawn below the zero line 50 is drawn on the zero line (which is invisible, see the third data point in the example) 51 to 100 is drawn above the zero line	chp=.5 chd=t:20,35,50,10,95
chds	An alternative way to set a zero line is to use the data scaling parameter (chds) in combination with text encoding. The example has a data set ranging from -60 to 120 and a scale of -80 to 140 to leave space above and below the bars. See text encoding with data scaling for more information.	chd=t:30,-60,50,120,80 chds=-80,140

Back to top

Line styles

You can specify line styles for:

• Line and sparkline charts: specifying thickness and dash style (and color with data set colors)
• Line, sparkline, and bar charts: specifying thickness, color, and priority

Line and sparkline styles

Specify line and sparkline styles with

chls=
<data set 1 line thickness>,<length of line segment>,<length of blank segment>|
...
<data set n line thickness>,<length of line segment>,<length of blank segment>


Parameter values are floating point numbers, multiple line styles are separated by the pipe character (|). The first line style is applied to the first data set, the second style to the second data set, and so on.

Parameter	Description	Example
chls	Here the thick dashed line is specified by 3,6,3 and the thinner solid line is specified by 1,1,0. See Chart colors for information on specifying line colors.	chls=3,6,3|1,1,0

Back to top

Line, sparkline, and bar chart line styles

Specify line and bar chart line styles with

chm=D,<color>,<data set index>,<data point>,<size>,<priority>

where:

• <color> is an RRGGBB format hexadecimal number.
• <data set index> the index of the data set on which to draw the line. This is 0 for the first data set, 1 for the second and so on.
• <data point> is zero.
• <size> is the size of the marker in pixels.
• <priority> determines the order in which bars, lines, markers, and fills are drawn:
  1 specifies the line is drawn on top of bars and markers.
  0 is the default and specifies the line is drawn on top of the bars and beneath markers.
  -1 specifies the line is drawn underneath bars and markers.

Parameter	Description	Example
chm=D	Here's an example of a data line on a bar chart. The priority is set to 1 so the line is drawn in front of the bars.	chm= D,4D89F9,0,0,5,-1
	Here's an example of a sparkline chart. Sparklines are identical to line charts, except they have no axes by default, they have exactly the same functionality as line charts.	chm= D,C6D9FD,1,0,8| D,4D89F9,0,0,4

Back to top

Grid lines

Specify a grid with

chg=
<x axis step size>,
<y axis step size>,
<length of line segment>,
<length of blank segment>

Parameter values can be integers or have a single decimal place - 10.0 or 10.5 for example.

Parameter	Description<