Google Visualization API Reference

This page lists the objects exposed by the Google Visualization API, and the standard methods exposed by all visualizations.

Note: The Google Visualization API namespace is google.visualization.*

google.visualization.DataTable

Represents a two-dimensional, mutable table of values. To make a read-only copy of a DataTable (optionally filtered to show specific values, rows, or columns), create a DataView.

Each column is assigned a data type, plus several optional properties including an ID, label, and pattern string.

In addition, you can assign custom properties (name/value pairs) to any cell, row, column, or the entire table. Some visualizations support specific custom properties; for example the Table visualization supports a cell property called 'style', which lets you assign an inline CSS style string to the rendered table cell. A visualization should describe in its documentation any custom properties that it supports.

See also: QueryResponse.getDataTable

Constructors

The DataTable class has two constructors:

google.visualization.DataTable()              // Create an empty DataTable instance
google.visualization.DataTable(data, version) // Create a populated DataTable instance

DataTable()

Creates an empty DataTable instance. Use JavaScript to populate the DataTable as shown in the following example, which creates and populates a two column, three row DataTable in JavaScript. You might use this on a page hosting a visualization to create the data for that visualization.

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

DataTable(data, version)

Creates a DataTable populated with the data that you pass in. You can see an example of this below.

Parameters

data

[Required] Data used to initialize the table. This can either be the JSON returned by calling DataTable.toJSON() on a populated table, or a JavaScript object containing data used to initialize the table. The structure of the JavaScript literal object is described here.

version

[Required] A numeric value specifying the version of the wire protocol used. The current version is 0.6.

Details

The DataTable object is used to hold the data passed into a visualization. A DataTable is a basic two-dimensional table. All data in each column must have the same data type. Each column has a descriptor that includes its data type, a label for that column (which might be displayed by a visualization), and an ID, which can be used to refer to a specific column (as an alternative to using column indexes). The DataTable object also supports a map of arbitrary properties assigned to a specific value, a row, a column, or the whole DataTable. Visualizations can use these to support additional features; for example, the Table visualization uses custom properties to let you assign arbitrary class names or styles to individual cells.

Each cell in the table holds a value. Cells can have a null value, or a value of the type specified by its column. Cells optionally can take a "formatted" version of the data; this is a string version of the data, formatted for display by a visualization. A visualization can (but is not required to) use the formatted version for display, but will always use the data itself for any sorting or calculations that it makes (such as determining where on a graph to place a point). An example might be assigning the values "low" "medium", and "high" as formatted values to numeric cell values of 1, 2, and 3.

To add data rows after calling the constructor, you can call either addRow() for a single row, or addRows() for multiple rows. You can add columns as well by calling the addColumn() methods. There are removal methods for rows and columns as well, but rather than removing rows or columns, consider creating a DataView that is a selective view of the DataTable.

If you change values in a DataTable after it is passed into a visualization's draw() method, the changes will not immediately change the chart. You must call draw() again to reflect any changes.

Example

The following example demonstrates instantiating and populating a DataTable with a literal string, with the same data as shown in the JavaScript example above:

var dt = new google.visualization.DataTable(
     {
       cols: [{id: 'task', label: 'Task', type: 'string'},
                {id: 'hours', label: 'Hours per Day', type: 'number'}],
       rows: [{c:[{v: 'Work'}, {v: 11}]},
              {c:[{v: 'Eat'}, {v: 2}]},
              {c:[{v: 'Commute'}, {v: 2}]},
              {c:[{v: 'Watch TV'}, {v:2}]},
              {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}
             ]
     },
   0.6
)

Should I create my DataTable in JavaScript or object literal notation?

You can create a DataTable either by calling the constructor without parameters and then adding values by calling the addColumn()/addRows() methods listed below, or by passing in a populated JavaScript literal object to initialize it. Both methods are described below. Which one should you use?

• Creating and populating a table in JavaScript by calling addColumn(), addRow(), and addRows() is very readable code. This method is useful when you'll be entering code by hand. It is slower than using object literal notation (described next), but in smaller tables (say, 1,000 cells) you probably won't notice much difference.
• Direct declaration of the DataTable object using object-literal notation is considerably faster in large tables. However, it can be a tricky syntax to get right; use this if you can generate the object literal syntax in code, which reduces possibility of errors.

Methods

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null]]); // No date set for Bob.

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}
        

Format of the Constructor's JavaScript Literal data Parameter

You can initialize a DataTable by passing a JavaScript string literal object into the data parameter. We'll call this object the data object. You can code this object by hand, according to the description below, or you can use a helper Python library if you know how to use Python, and your site can use it. However, if you want to construct the object by hand, this section will describe the syntax.

First, let's show an example of a simple JavaScript object describing a table with three rows and three columns (String, Number, and Date types):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
        ],
  rows: [{c:[{v: 'a'}, {v: 1.0, f: 'One'}, {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}]},
         {c:[{v: 'b'}, {v: 2.0, f: 'Two'}, {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}]},
         {c:[{v: 'c'}, {v: 3.0, f: 'Three'}, {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}]}
        ],
  p: {foo: 'hello', bar: 'world!'}
}

Now let's describe the syntax:

The data object consists of two required top-level properties, cols and rows, and an optional p property that is a map of arbitrary values.

Note: All property names and string constants shown are case-sensitive. Also, properties described as taking a string value should have their value enclosed in quotation marks. For example, if you wish to specify the type property as being number, it would be expressed like this: type: 'number' but the value itself, as numeric, would be expressed like this: v: 42

cols property

cols is an array of objects describing the ID and type of each column. Each property is an object with the following properties (case-sensitive):

• type [Required] Data type of the data in the column. Supports the following string values (examples include the v: property, described later):
  • 'boolean' - JavaScript boolean value ('true' or 'false'). Example value: v:'true'
  • 'number' - JavaScript number value. Example values: v:7 , v:3.14, v:-55
  • 'string' - JavaScript string value. Example value: v:'hello'
  • 'date' - JavaScript Date object (zero-based month), with the time truncated. Example value: v:new Date(2008, 0, 15)
  • 'datetime' - JavaScript Date object including the time. Example value: v:new Date(2008, 0, 15, 14, 30, 45)
  • 'timeofday' - Array of three numbers and an optional fourth, representing hour (0 indicates midnight), minute, second, and optional millisecond. Example values: v:[8, 15, 0], v: [6, 12, 1, 144]
• id [Optional] String ID of the column. Must be unique in the table. Use basic alphanumeric characters, so the host page does not require fancy escapes to access the column in JavaScript. Be careful not to choose a JavaScript keyword. Example: id:'col_1'
• label [Optional] String value that some visualizations display for this column. Example: label:'Height'
• pattern [Optional] String pattern that was used by a data source to format numeric, date, or time column values. This is for reference only; you probably won't need to read the pattern, and it isn't required to exist. The Google Visualization client does not use this value (it reads the cell's formatted value). If the DataTable has come from a data source in response to a query with a format clause, the pattern you specified in that clause will probably be returned in this value. The recommended pattern standards are the ICU DecimalFormat and SimpleDateFormat.
• p [Optional] An object that is a map of custom values applied to the cell. These values can be of any JavaScript type. If your visualization supports any cell-level properties, it will describe them; otherwise, this property will be ignored. Example: p:{style: 'border: 1px solid green;'}.

cols Example

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

rows property

The rows property holds an array of row objects.

Each row object has one required property called c, which is an array of cells in that row. It also has an optional p property that defines a map of arbitrary custom values to assign to the whole row. If your visualization supports any row-level properties it will describe them; otherwise, this property will be ignored.

Cells

Each cell in the table is described by an object with the following properties:

• v [Optional] The cell value. The data type should match the column data type. If null, the whole object should be empty and have neither v nor f properties.
• f [Optional] A string version of the v value, formatted for display. The values should match, so if you specify Date(2008, 0, 1) for v, you should specify "January 1, 2008" or some such string for this property. This value is not checked against the v value. The visualization will not use this value for calculation, only as a label for display. If omitted, a string version of v will be used.
• p [Optional] An object that is a map of custom values applied to the cell. These values can be of any JavaScript type. If your visualization supports any cell-level properties, it will describe them; otherwise, this property will be ignored. Example: p:{style: 'border: 1px solid green;'}.

Cells in the row array should be in the same order as their column descriptions in cols. To indicate a null cell, you can specify null, leave a blank for a cell in an array, or omit trailing array members. So, to indicate a row with null for the first two cells, you could specify [ , , {cell_val}] or [null, null, {cell_val}].

Here is a sample table object with three columns, filled with three rows of data:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
        ],
  rows: [{c:[{v: 'a'}, {v: 1.0, f: 'One'}, {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}]},
         {c:[{v: 'b'}, {v: 2.0, f: 'Two'}, {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}]},
         {c:[{v: 'c'}, {v: 3.0, f: 'Three'}, {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}]}
        ]
}

p property

The p property is a map of custom values applied to the whole DataTable. These values can be of any JavaScript type. If your visualization supports any datatable-level properties, it will describe them; otherwise, this property will be ignored. Example: p:{className: 'myDataTable'}.

google.visualization.DataView

A read-only view of an underlying DataTable. A DataView allows selection of only a subset of the columns and/or rows. It also allows reordering columns/rows, and duplicating columns/rows.

A view is a live window on the underlying DataTable, not a static snapshot of data. However, you still should must be careful when changing the structure of the table itself, as described here:

• Adding or removing columns from the underlying table will not be reflected by the view, and might cause unexpected behavior in the view; you will have to create a new DataView from the DataTable to pick up these changes.
• Adding or removing rows from the underlying table is safe and changes will be propagated to the view immediately (but you must call draw() on any visualizations after this change to have the new row set rendered). Note that if your view has filtered out rows by calling one of the setRows() or hideRows() methods, and you add or remove rows from the underlying table, the behavior is unexpected; you must create a new DataView to reflect the new table.
• Changing cell values in existing cells is safe, and changes are immediately propagated to the DataView (but you must call draw() on any visualizations after this change to have the new cell values rendered).

It is also possible to create a DataView from another DataView. Note that whenever an underlying table or view is mentioned, it refers to the level immediately below this level. In other words, it refers to the data object used to construct this DataView.

DataView also supports calculated columns; these are columns whose value is calculated on the fly using a function that you supply. So, for example, you can include a column that is a sum of two preceding columns, or a column that calculates and shows the calendar quarter of a date from another column. See setColumns() for more details.

When you modify a DataView by hiding or showing rows or columns, the visualization will not be affected until you call draw() on the visualization again.

You can combine DataView.getFilteredRows() with DataView.setRows() to create a DataView with an interesting subset of data, as shown here:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

Constructors

Constructor 1: google.visualization.DataView

Parameters

data

A DataTable or DataView used to initialize the view. By default, the view contains all the columns and rows in the underlying data table or view, in the original order. To hide or show rows or columns in this view, call the appropriate set...() or hide...() methods.

See also:

setColumns(), hideColumns(), setRows(), hideRows().

Constructor 2: google.visualization.DataView.fromJSON

This constructor creates a DataView object initialized from a JSON string. It helps you recreate the DataView that you serialized using DataView.toJSON(). You must pass in the DataTable that was used to create the original DataView on which you called DataView.toJSON().

Syntax

google.visualization.DataView.fromJSON(data, viewAsJson)

data

The DataTable object that you used to create the DataView, on which you called DataView.toJSON(). If this table is any different from the original table, you will get unpredictable results.

viewAsJson

The JSON string returned by DataView.toJSON().

Methods

view.setColumns([3, 4, 3, 2]); //Causes column 3 to appear twice in the view, 
                               //and hide columns 0 and 1 (as well as any columns
                               //past 4).

// Column 1 is a value in centimeters, and the third column is
// a generated column that converts this into inches.
view.setColumns([0,1,{calc:myFunc, type:'number', label:'Height in Inches'}]);
function myFunc(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

google.visualization.data

The google.visualization.data namespace holds a variety of static methods to perform SQL-like operations on DataTable objects, for example joining them or grouping by column value.

The google.visualization.data namespace exposes the following methods:

google.visualization.data.group()

Takes a populated DataTable object and performs a SQL-like GROUP BY operation, returning a table with rows grouped by the specified column values. Note that this does not modify the input DataTable.

The returned table includes one row for each combination of values in the specified key columns. Each row includes the key columns, plus one column with an aggregated column value over all rows that match the key combination (for example, a sum or count of all values in the specified column).

The google.visualization.data namespace includes several useful aggregation values (for example, sum and count), but you can define your own (for example, standardDeviation or secondHighest). Instructions on how to define your own aggregator are given after the method description.

Syntax

google.visualization.data.group(dt, keys, columns)

dt

The input DataTable. This will not be modified by calling group().

keys

An array of numbers and/or objects specifying which columns to group by. The result table includes every column in this array, as well as every column in columns. If a number, this is a column index of the input DataTable to group by. If an object, it will include a function that can modify the specified column (for example, add 1 to the value in that column). The object must have the following properties:

• column - A number that is a column index from dt to apply the transformation to.
• modifier - A function that accepts one value (the cell value in that column for each row), and returns the modified value. This function is used to modify the column value to assist in the grouping: for example, by calling a whichQuarter function that calculates a quarter from a date column, so the API can group rows by quarter. The calculated value is displayed in the key columns in the returned table. This function can be declared inline inside this object, or it can be a function that you define elsewhere in your code (it must be within the calling scope). The API provides one simple modifier function; here are instructions on how to create your own, more useful functions. You must know the data type that this function can accept, and call it only on columns of that type. You must also know the return type of this function, and declare it in the type property described next.
• type - The type returned by the function modifier. This should be a JavaScript string type name, for example: 'number' or 'boolean'.
• label - [Optional] A string label to assign this column in the returned DataTable.
• id - [Optional] A string ID to assign this column in the returned DataTable.

Examples: [0], [0,2], [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

columns

[Optional] Lets you specify which columns, in addition to key columns, to include in the output table. Because all rows in the row group are compressed into a single output row, you must determine what value to display for that row group. For example, you could choose to show the column value from the first row in the set, or an average of all rows in that group. columns is an array of objects, with the following properties:

• column - A number specifying the index of the column to show.
• aggregation - A function that accepts an array of all values of this column in this row group and returns a single value to display in the result row. The return value must be of the type specified by the object's type property. Details on creating your own aggregation function are given below. You must know what data types this method accepts and only call it on columns of the appropriate type. The API provides several useful aggregation functions. See Provided Aggregation Functions below for a list, or Creating an aggregation function to learn how to write your own aggregation function.
• type - The return type of the aggregation function. This should be a JavaScript string type name, for example: 'number' or 'boolean'.
• label - [Optional] A string label to apply to this column in the returned table.
• id - [Optional] A string ID to apply to this column in the returned table.

Return Value

A DataTable with one column for each column listed in keys and one column for each column listed in columns. The table is sorted by key rows, from left to right.

Example

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of 
// values in that column for that row group.
var result = google.visualization.data.group(
  dt, 
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

Provided Modifier Functions

The API provides the following modifier functions that you can pass into the keys.modifier parameter to customize grouping behavior.

Provided Aggregation Functions

The API provides the following aggregation functions that you can pass into the columns.aggregation parameter array.

Creating a modifier function

You can create a modifier function to perform a simple transformation on key values before the group() function groups your rows. This function takes a single cell value, performs an action on it (for example, adds 1 to the value), and returns it. The input and return types need not be the same type, but the caller must know the input and output types. Here's an example of a function that accepts a date and returns the quarter:

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) { 
  return Math.floor(someDate.getMonth()/3) + 1;

}

Creating an aggregation function

You can create an aggregation function that accepts a set of column values in a row group and returns a single number: for example, returning a count or average of values. Here is an implementation of the provided count aggregation function, which returns a count of how many rows are in the row group:

// Input type: Array of any type
// Return type: number
function count(values) { 
  return values.length;
}

google.visualization.data.join()

This method joins two data tables (DataTable or DataView objects) into a single results table, similar to a SQL JOIN statement. You specify one or more column pairs (key columns) between the two tables, and the output table includes the rows according to a join method that you specify: only rows where both keys match; all rows from one table; or all rows from both tables, whether or not the keys match. The results table includes only the key columns, plus any additional columns that you specify. Note that dt2 cannot have duplicate keys, but dt1 can. The term "key" means the combination of all key column values, not a specific key column value; so if a row has cell values A | B | C and columns 0 and 1 are key columns, then the key for that row is AB.

Syntax

google.visualization.data.join(dt1, dt2, joinMethod, keys, dt1Columns, dt2Columns)

dt1

A populated DataTable to join with dt2.

dt2

A populated DataTable to join with dt1. This table cannot have multiple identical keys (where a key is a combination of key column values).

joinMethod

A string specifying the join type. If dt1 has multiple rows that match a dt2 row, the output table will include all matching dt1 rows. Choose from the following values:

• 'full' - The output table includes all rows from both tables, regardless of whether keys match. Unmatched rows will have null cell entries; matched rows are joined.
• 'inner' - The full join filtered to include only rows where the keys match.
• 'left' - The output table includes all rows from dt1, whether or not there are any matching rows from dt2.
• 'right' - The output table includes all rows from dt2, whether or not there are any matching rows from dt1.

keys

An array of key columns to compare from both tables. Each pair is a two element array, the first is a key in dt1, the second is a key in dt2. Columns must be the same type in both tables. All specified keys must match according to the rule given by joinMethod in order to include a row from the table. Key columns are always included in the output table. Only dt1, the left-hand table, can include duplicate keys; keys in dt2 must be unique. The term "key" here means a unique set of key columns, not individual column values. For example, if your key columns were A and B, the following table would have only unique key values (and could thus be used as dt2):
A  |  B
Jen  Red
Jen  Blue
Fred Red
Example: [[0,0], [2,1]] compares values from the first column in both tables as well as the third column from dt1 with the second column from dt2.

dt1Columns

An array of columns from dt1 to include in the output table, in addition to dt1's key columns. This is an array of column indexes.

dt2Columns

An array of columns from dt2 to include in the output table, in addition to dt2's key columns. This is an array of column indexes.

Return Value

A DataTable with the key columns, dt1Columns, and dt2Columns. This table is sorted by the key columns, from left to right. When joinMethod is 'inner', all key cells should be populated. For other join methods, if no matching key is found, the table will have a null for any unmatched key cells.

Examples

*Tables*
       dt1                         dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is 
* columns 0 and 1. The left table has duplicate key values, but that is 
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to 
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle
 

Formatters

The Google Visualization API provides formatters that can be used to reformat data in a visualization. These formatters change the formatted value of the specified column in all rows. Note that it does not modify the underlying values; just the formatted values. So, for example, the displayed value would be "$1,000.00" but the underlying value would still be "1000". Formatters can only affect one column at a time; to reformat multiple columns, apply a formatter to each column that you want to change.

Important: Formatters can only be used with a DataTable; they cannot be used with a DataView (DataView objects are read-only).

Here are the general steps for using a formatter:

1. Get your populated DataTable object.
2. For each column that you want to reformat:
   1. Create an object that specifies all the options for your formatter. This is a basic JavaScript object with a set of properties and values. Look at your formatter's documentation to see what properties are supported. (Optionally, you can pass in an object literal notation object specifying your options.)
   2. Create your formatter, passing in your options object.
   3. Call formatter.Format(table, colIndex), passing in the DataTable and the (zero-based) column number of the data to reformat. Note that you can only apply a single formatter to each column; applying a second formatter will simply overwrite the effects of the first.
      Important: Many formatters require HTML tags to display special formatting; if your visualization supports an allowHtml option, you should set it to true.

Here is an example of changing the formatted date values of a date column to use a long date format ("January 1, 2009"):

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});
  

Most formatters expose the following two methods:

// Object literal technique
var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5});

// Equivalent property setting technique
var options = new Object();
options['formatType'] = 'long';
options['timeZone'] = -5;
var formatter = new google.visualization.DateFormat(options);
      

The Google Visualization API provides the following formatters:

google.visualization.ArrowFormat

Adds an up or down arrow to a numeric cell, depending on whether the value is above or below a specified base value. If equal to the base value, no arrow is shown.

Options

ArrowFormat supports the following options, passed in to the constructor:

Example

  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Department');
  data.addColumn('number', 'Revenues Change');
  data.addRows([
    ['Shoes', {v:12, f:'12.0%'}],
    ['Sports', {v:-7.3, f:'-7.3%'}],
    ['Toys', {v:0, f:'0%'}],
    ['Electronics', {v:-2.1, f:'-2.1%'}],
    ['Food', {v:22, f:'22.0%'}]
  ]);

  var table = new google.visualization.Table(document.getElementById('arrowformat_div'));
  
  var formatter = new google.visualization.ArrowFormat();
  formatter.format(data, 1); // Apply formatter to second column
  
  table.draw(data, {allowHtml: true, showRowNumber: true});
    

google.visualization.BarFormat

Adds a colored bar to a numeric cell indicating whether the cell value is above or below a specified base value.

Options

BarFormat supports the following options, passed in to the constructor:

  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Department');
  data.addColumn('number', 'Revenues');
  data.addRows([
    ['Shoes', 10700],
    ['Sports', -15400],
    ['Toys', 12500],
    ['Electronics', -2100],
    ['Food', 22600],
    ['Art', 1100]
  ]);

  var table = new google.visualization.Table(document.getElementById('barformat_div'));
  
  var formatter = new google.visualization.BarFormat({width: 120});
  formatter.format(data, 1); // Apply formatter to second column
  
  table.draw(data, {allowHtml: true, showRowNumber: true});
  

google.visualization.ColorFormat

Assigns colors to the foreground or background of a numeric cell, depending on the cell value. This formatter is an unusual, in that it doesn't take its options in the constructor. Instead, you should call addRange() or addGradientRange() as many times as you want, to add color ranges, before calling format(). Colors can be specified in any acceptable HTML format, for example "black", "#000000", or "#000".

Methods

ColorFormat supports the following methods:

Example

  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Department');
  data.addColumn('number', 'Revenues');
  data.addRows([
    ['Shoes', 10700],
    ['Sports', -15400],
    ['Toys', 12500],
    ['Electronics', -2100],
    ['Food', 22600],
    ['Art', 1100]
  ]);

  var table = new google.visualization.Table(document.getElementById('colorformat_div'));
  
  var formatter = new google.visualization.ColorFormat();
  formatter.addRange(-20000, 0, 'white', 'orange');
  formatter.addRange(20000, null, 'red', '#33ff33');
  formatter.format(data, 1); // Apply formatter to second column
  
  table.draw(data, {allowHtml: true, showRowNumber: true});
  

google.visualization.DateFormat

Formats a JavaScript Date value in a variety of ways, including "January 1, 2009," "1/1/09" and "Jan 1, 2009.

Options

DateFormatter supports the following options, passed in to the constructor:

Example

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26), new Date(2008, 1, 28, 0, 31, 26), new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0), new Date(2007, 5, 1, 0), new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16), new Date(2006, 7, 16), new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true});
}
  

More About Date Patterns

Here are some more details on what patterns are supported:

The patterns are similar to the ICU date and time format, but the following patterns are not yet supported: A e D F g Y u w W. To avoid collision with patterns, any literal text you want to appear in the output should be surrounded by single quotes, except for the single quote, which should be doubled: e.g.,"K 'o''clock.'".

google.visualization.NumberFormat

Describes how numeric columns should be formatted. Formatting options include specifying a prefix symbol (such as a dollar sign) or the punctuation to use as a thousands marker.

Options

NumberFormat supports the following options, passed in to the constructor:

Example

  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Department');
  data.addColumn('number', 'Revenues');
  data.addRows([
    ['Shoes', 10700],
    ['Sports', -15400],
    ['Toys', 12500],
    ['Electronics', -2100],
    ['Food', 22600],
    ['Art', 1100]
  ]);

  var table = new google.visualization.Table(document.getElementById('numberformat_div'));
  
  var formatter = new google.visualization.NumberFormat(
      {prefix: '$', negativeColor: 'red', negativeParens: true});
  formatter.format(data, 1); // Apply formatter to second column
  
  table.draw(data, {allowHtml: true, showRowNumber: true});

google.visualization.PatternFormat

Enables you to merge the values of designated columns into a single column, along with arbitrary text. So, for example, if you had a column for first name and a column for last name, you could populate a third column with {last name}, {first name}. This formatter does not follow the conventions for the constructor and the format() method. See the Methods section below for instructions.

Methods

PatternFormat supports the following methods:

 var formatter = new google.visualization.PatternFormat('<a href="mailto:{1}">{0}</a>');         

Here are a few example inputs and outputs for a four-column table.

Row before formatting (4 columnss, last is blank):
  John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John
    

Example

The following example demonstrates how to combine data from two columns to create an email address. It uses a DataView object to hide the original source columns:

  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Name');
  data.addColumn('string', 'Email');
  data.addRows([
    ['John Lennon', 'john@beatles.co.uk'],
    ['Paul McCartney', 'paul@beatles.co.uk'],
    ['George Harrison', 'george@beatles.co.uk'],
    ['Ringo Starr', 'ringo@beatles.co.uk']
  ]);

  var table = new google.visualization.Table(document.getElementById('patternformat_div'));
  
  var formatter = new google.visualization.PatternFormat('<a href="mailto:{1}">{0}</a>');
  formatter.format(data, [0, 1]); // Apply formatter and set the formatted value of the first column.

  var view = new google.visualization.DataView(data);
  view.setColumns([0]); // Create a view with the first column only.
  
  table.draw(view, {allowHtml: true, showRowNumber: true});
  

google.visualization.GadgetHelper

A helper class to simplify writing Gadgets that use the Google Visualization API.

Constructor

google.visualization.GadgetHelper()

Methods

google.visualization.Query

Represents a query that is sent to a data source.

Constructor

google.visualization.Query(dataSourceUrl, opt_options)

Parameters

dataSourceUrl

[Required, String] URL to send the query to. The data source should expose this URL in some way; for example, to get the dataSourceUrl from a Google Spreadsheet, do the following:

1. In your spreadsheet, select the range of cells.
2. Select 'Insert' and then 'Gadget' from the menu.
3. Open the gadget's menu by clicking on the top-right selector.
4. Select menu option 'Get data source URL'.

opt_options

[Optional, Object] A map of options for the request. Note: If you are accessing a restricted data source, you should not use this parameter. Here are the supported properties:

• sendMethod - [Optional, String] Specifies the method to use to send the query. Choose one of the following string values:
  • 'xhr' - Send the query using XmlHttpRequest.
  • 'scriptInjection' - Send the query using script injection.
  • 'makeRequest' - [Available only for gadgets] Send the query using the Gadget API  makeRequest() method. If specified, you should also specify makeRequestParams.
  • 'auto' - Use the method specified by the tqrt URL parameter from the data source URL. tqrt can have the following values: 'xhr', 'scriptInjection', or 'makeRequest'. If tqrt is missing or has an invalid value, the default is 'xhr' for same-domain requests and 'scriptInjection' for cross-domain requests.
• makeRequestParams - [Object] A map of parameters for a makeRequest() query. Used and required only if sendMethod is 'makeRequest'.

Methods

google.visualization.QueryResponse

Represents a response of a query execution as received from the data source. An instance of this class is passed as an argument to the callback function that was set when Query.send was called.

See also: Query.send

Methods

google.visualization.drawToolbar()

This is the constructor for the toolbar element that can be attached to many visualizations. This toolbar enables the user to export the visualization data into different formats, or to provide an embeddable version of the visualization for use in different places. See the toolbar page for more information and a code example.

google.visualization.errors

The API provides several functions to help you display custom error messages to your users. To use these functions, provide a container element on the page (typically a <div>), into which the API will draw a formatted error message. This container can be either the visualization container element, or a container just for errors. If you specify the visualization container element, the error message will be displayed above the visualization. Then call the appropriate function below to show, or remove, the error message. All functions are static functions in the namespace google.visualization.errors.

You can see an example custom error in the Query Wrapper Example.

Events

Registering to Catch Events

Your visualizations can fire and receive events, and exposes the following two methods to enable you to do so:

• google.visualization.events.trigger()
• google.visualization.events.addListener()

Commonly Exposed Events

Visualizations can fire a number of events. Every visualization can define the details of the events it fires, but the following event should be implemented in a standard way:

• ready event
• select event

trigger()

Called by visualization implementers. Call this method from your visualization to fire an event with an arbitrary name and set of values.

google.visualization.events.trigger(source_visualization, event_name, event_args)

source_visualization

A handle to the source visualization instance. If you are calling this function from within a method defined by the sending visualization, you can simply pass in the this keyword.

event_name

A string name to call the event. You can choose any string value that you want.

event_args

[optional] A map of name/value pairs to pass to the receiving method. For example: {message: "Hello there!", score: 10, name: "Fred"}. You can pass null if no events are needed; the receiver should be prepared to accept null for this parameter.

Example

Here is an example of a visualization that throws a method named "select" when its onclick method is called. It does not pass back any values.

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Trigger a select event.
  google.visualization.events.trigger(this, 'select', null);
};

addListener()

Used by visualization users. Call this method to register to receive events fired by a visualization hosted on your page. Note that this will not work for gadget visualizations. The visualization should document what event arguments, if any, will be passed to the handling function.

google.visualization.events.addListener(source_visualization, event_name, handling_function)

source_visualization

A handle to the source visualization instance.

event_name

The string name of the event to listen for. A visualization should document which events it throws.

handling_function

The name of the local JavaScript function to call when source_visualization fires the event_name event. The handling function will be passed any event arguments as parameters.

Example

Here is an example of registering to receive the selection event

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

ready Event

If your visualization is not expected to be ready for interaction immediately after it returns from its draw() implementation, consider implementing a ready event. This event should be fired when the visualization is ready to begin responding to user interaction and method calls. This event typically does not provide any parameters to the receiver. See the Firing Events page for more information.

select Event

If your visualization can fire events to the client when selected, consider implementing the select event. Details on the standard way to implement this event are given on the Firing Events page.

Standard Visualization Methods and Properties

Every visualization should expose the following set of required and optional methods and properties. However, note that there is no type checking to enforce these standards, so you should read the documentation for each visualization.

• Constructor
• draw()
• getSelection() [optional]
• setSelection() [optional]

Note: These methods are in the namespace of the visualization, not the google.visualization namespace.

Constructor

The constructor should have the name of your visualization class, and return an instance of that class.

visualization_class_name(dom_element)

dom_element

A pointer to a DOM element where the visualization should be embedded.

Example

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

draw()

Draws the visualization on the page. Behind the scenes this can be fetching a graphic from a server or creating the graphic on the page using the linked visualization code. You should call this method every time the data or options change. The object should be drawn inside the DOM element passed into the constructor.

draw(data[, options])

data

A DataTable holding the data to use to draw this graphic. There is no standard method for getting the underlying DataTable passed into a visualization.

options

[Optional] A map of name/value pairs of custom options. Examples include height and width, background colors, and captions. The visualization documentation should list which options are available, and should support default options if you do not specify this parameter. You can use the JavaScript object literal syntax to pass in an options map: e.g., {x:100, y:200, title:'An Example'}

Example

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getSelection() [optional]

This is optionally exposed by visualizations that want to let you access the currently selected data in the graphic.

selection_array getSelection()

Returns

selection_array   An array of selected objects, each one describing a data element in the underlying table. Each object has properties row and/or column, with the index of the row and/or column of the selected item in the underlying DataTable. If the row property is null, then the selection is a column; if the column property is null, then the selection is a row; if both are non-null, then it is a specific data item. You can call the DataTable.getValue() method to get the value of the selected item. The retrieved array can be passed into setSelection().

Example

function myClickHandler(){
  var selection = myVis.getSelection();


  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

setSelection() [optional]

Selects a data entry in the visualization--for example, a point in an area chart, or a bar in a bar chart. When this method is called, the visualization should visually indicate what the new selection is. The implementation of setSelection() should not fire a "select" event. Visualizations may ignore part of the selection. For example, a table that can show only selected rows may ignore cell or column elements in its setSelection() implementation, or it can select the entire row.

Every time this method is called, all selected items are deselected, and the new selection list passed in should be applied. There is no explicit way to deselect individual items; to deselect individual items, call setSelection() with the items to remain selected; to deselect all elements, call setSelection(), setSelection(null), or setSelection([]).

setSelection(selection_array)

selection_array

An array of objects, each with a numeric row and/or column property. row and column are the zero-based row or column number of an item in the data table to select. To select a whole column, set row to null; to select a whole row, set column to null. Example: setSelection([{row:0,column:1},{row:1, column:null}]) selects the cell at (0,1) and the entire row 1.