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 Extended! Introduction URL format Required and optional parameters Extended! Chart size Chart data Text encoding Text encoding with data scaling New! Simple encoding Extended encoding JavaScript snippet for encoding data Guidelines for granularity Chart type Line charts Sparklines New! Bar charts Pie charts Venn diagrams Scatter plots Radar charts New! Maps New! Google-o-meter New!

Colors Chart colors Solid fill Extended! Linear gradient Linear stripes Fill area Labels Chart title Chart legend Pie chart and Google-o-meter labels Multiple axis labels Styles Bar width and spacing Bar chart zero line New! Line styles Extended! Grid lines Shape and range markers Extended! 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: line, bar, and pie charts for example. 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.

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 100.0, minus one (-1), and the pipe character (|).

Note:

• Zero (0.0) = 0, 1.0 = 1 and so on up to 100.0 = 100.
• 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.
• 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 (,).

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.
• 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 (,).

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.
• 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

JavaScript snippet for encoding data

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. 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 section Shape markers. Specify line colors as described in section 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 axes lines are not drawn for sparklines by default. You can add axes labels if you wish, see section Multiple axis labels.

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 series. 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 section 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 section 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

• 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 section 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.

• 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	Here's a simple example to get started with. 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 the maximum value for the encoding used (100, 9 or ..) is drawn at the perimeter. Intermediate values are scaled between the two. The first and last values in the data series are drawn between the center of the chart and the top of the chart. All others are evenly spaced traveling clockwise around the chart.	cht=r chd=t:10,20,30,40,50,60,70,80,90
cht=r	Here's a much more interesting example. This chart has two data sets, the color of each is specified with chco, see section Chart colors for more information. Line styles are specified with chls, see section Line styles for more information. Labels are specified with chxt, chxl, and chxr, see section Multiple axis labels for more information. For radar charts the x-axis is drawn in a circle, the y and r axes 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 is the same example as the one above but with fill area specified for both data sets. See Fill area for more information. Also, a grid is specified, see section 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
	This example has shape markers specified: 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 sections Shape markers and Colors for information. You can also specify range markers. See section 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 section ISO 3166 Country codes.
  • USA state codes as listed in section 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 section 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

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 series 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. zz	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 section 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 series, it is simpler to use chm=B. In this case all the area under the line is filled.	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.

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 section Colors. In these examples the first data set is drawn in red, the second in green and the third in blue.	chdl=First|Second|Third chco=ff0000,00ff00,0000ff
		chdl=First|Second|Third chco=ff0000,00ff00,0000ff

Back to top

Pie chart and Google-o-meter labels

For a pie chart specify labels with

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

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
	Of course, this depends on 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	This example shows two lower x-axes (x is included twice), left and right y-axes (y and r) plus one top axis (t). Note: Because axis labels are omitted the Chart API assumes a range of 0 to 100 for all axes.	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	This example shows left and right y-axes (y and r) plus two sets of values for the x-axis (x). Note: the pipe character (|) is not required after the last parameter.	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 except left y-axis labels (y) are not specified (the 1: index is not included in the chxl parameter). Note: the pipe character (|) is not required after the last parameter.	chxt=x,y,r,x chxl= 0:|Jan|July|Jan|July|Jan| (y-axis omitted) 2:|A|B|C| 3:|2005|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. The Chart API therefore assumes a range of 0 to 100 and spaces the values evenly. The left y-axis (y) has both labels (max, average, and min) and positions (10,35,75). The right y-axis (r) has only positions (0,1,2,4) so the Chart API uses the positions as the labels.	chxt=x,y,r chxl=1:|min|average|max chxp=1,10,35,75|2,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. Note: Axis direction is reversed for the left y-axis (r) 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	Example
chg	An example where only step size is defined (20,50) so the Chart API defaults to a dashed grid line.	chg=20,50
	Here step size (20,50), line segment (1), and blank segment (5) are defined.	chg=20,50,1,5
	A solid grid is achieved by specifying a blank segment of zero (0).	chg=20,50,1,0

Back to top

Shape and range markers

For line charts, radar charts, bar charts, and scatter plots specify shape markers, horizontal, and vertical range markers with chm

• Shape markers
• Range markers

Shape markers

Specify shape markers with

chm=
<marker type>,<color>,<data set index>,<data point>,<size>,<priority>|
...
<marker type>,<color>,<data set index>,<data point>,<size>,<priority>

Where:

• <marker type> is one of the following characters:
  a represents an arrow.
  c represents a cross.
  d represents a diamond.
  o represents a circle.
  s represents a square.
  t represents text.
  v represents a vertical line from the x-axis to the data point.
  V represents a vertical line to the top of the chart.
  h represents a horizontal line across the chart.
  x represents an x shape.
  
  
• <color> is an RRGGBB format hexadecimal number.
• <data set index> the index of the line on which to draw the marker. This is 0 for the first data set, 1 for the second and so on.
• <data point> for all markers except a horizontal line, this is a floating point value that specifies on which data point the marker will be drawn. This is 0 for the first data point, 1 for the second and so on. Specify a fraction to interpolate a marker between two data points. For a horizontal line see the first example in the following table.
• <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 marker is drawn before all other parts of the chart. This means the marker will be hidden if another chart element is drawn in the same place.
  0 is the default and specifies the marker is drawn on top of bars or lines and beneath other markers.
  1 specifies the marker is drawn on top of all other parts of the chart. This means it will hide another chart element if it is drawn in the same place.
  

Separate multiple markers with the pipe character (|).

Parameter	Description	Example
chm	Here's an example of the full set of shape and line markers. The last marker in the list, h, is the horizontal line that intersects the vertical lines, v and V. For this type of marker do not specify a data point. Instead use 0.0 to place the line at the bottom of the chart, 1.0 to place the line at the top of the chart and a value between to the two to interpolate. The example has a value of 0.3 so the line is drawn about a third of the way up the chart.	chm= c,FF0000,0,1.0,20.0| d,80C65A,0,2.0,20.0| a,990066,0,3.0,9.0| o,FF9900,0,4.0,20.0| s,3399CC,0,5.0,10.0| v,BBCCED,0,6.0,1.0| V,3399CC,0,7.0,1.0| x,FFCC33,0,8.0,20.0| h,000000,0,0.30,0.5
	Here's an example of marker type s on a scatter plot. See the Scatter plot section for details on setting the size of each data point.	chm= s,FF0000,1,1.0,10.0
	Here's an example using diamonds and circles for two data sets. If two data points occupy the same place (by having the same x and y values), the first point specified is drawn. Here the circle takes precedence over the diamond.	chm= o,ff9900,0,1.0,10.0| o,ff9900,0,2.0,10.0| o,ff9900,0,3.0,10.0| d,ff9900,1,1.0,10.0| d,ff9900,1,2.0,10.0| d,ff9900,1,3.0,10.0
	Here's a bar chart with text as a marker. Specify text markers in the same order as your data. There is an optional fifth value that determines priority: 0 is the default where text is drawn on top of the bars and beneath other markers. This is what you see in the example chart for the second bar down (April desktop hits). 1 where text is drawn on top of the bars and other markers. -1 where text is drawn underneath bars and other markers. This is what you see in the example chart for the third bar down (May mobile hits).	chm= tApril+mobile+hits,000000,0,0,13| tMay+mobile+hits,000000,0,1,13,-1| tApril+desktop+hits,000000,1,0,13| tMay+desktop+hits,000000,1,1,13

Back to top

Range markers

For line charts, radar charts, bar charts, and scatter plots specify horizontal and vertical range markers with

chm=
<r or R>,<color>,<any value>,<start point>,<end point>|
...
<r or R>,<color>,<any value>,<start point>,<end point>

Where:

• <r or R> is r for a horizontal range and R for a vertical range.
• <color> is an RRGGBB format hexadecimal number.
• <any value> is ignored.
• <start point> for:
  - horizontal range markers is the position on the y-axis at which the range starts where 0.00 is the bottom and 1.00 is the top.
  - vertical range markers is the position on the x-axis at which the range starts where 0.00 is the left and 1.00 is the right.
• <end point> for:
  - horizontal range markers is the position on the y-axis at which the range ends where 0.00 is the bottom and 1.00 is the top.
  - for vertical range markers is the position on the x-axis at which the range ends where 0.00 is the left and 1.00 is the right.

Separate multiple range markers with the pipe character (|).

Parameter	Description	Example
chm=r	Range markers can be a single line or a band of color. Here the first marker is a pale blue (E5ECF9) band while the second is a line in black (000000).	chm= r,E5ECF9,0,0.75,0.25| r,000000,0,0.1,0.11
chm=R	Here's the same example for vertical range markers. In this case, the first marker is a line in red (ff0000) while the second is a pale blue (A0BAE9) band.	chm= R,ff0000,0,0.1,0.11| R,A0BAE9,0,0.75,0.25
chm= R...|r...	You can mix horizontal and vertical range markers. Note that the last marker specified takes precedence over previous markers if they overlap. Here the horizontal markers are specified last - so they are drawn over the top of the vertical markers.	chm= R,ff0000,0,0.1,0.11| R,A0BAE9,0,0.75,0.25| r,E5ECF9,0,0.75,0.25| r,000000,0,0.1,0.11
chm=r	Here's a sparkline that combines faint horizontal lines with chart labels on the right hand y-axis.	chm= r,000000,0,0.499,0.501| r,000000,0,0.998,1.0| r,000000,0,0.0,0.002

Back to top

Character mappings

Simple encoding character values

Simple encoding mapping is provided below.

Character	Value
A	0
B	1
C	2
D	3
E	4
F	5
G	6
H	7
I	8
J	9
K	10
L	11
M	12
N	13
O	14
P	15
Q	16
R	17