English | Site Directory

Google Visualization API

Google Visualization API Reference

The Google Visualization namespace is google.visualization.*

  1. DataTable
  2. GadgetHelper
  3. Query
  4. QueryResponse

google.visualization.DataTable

Represents a two-dimensional table of values. Every column has a single data type.

See also: QueryResponse.getDataTable

Constructors

google.visualization.DataTable()

Methods

Method Return Value Description
addColumn(type [,label [,id]]) number Adds a new column to the data table, and returns the index of the new column. All the cells of the new column are assigned a null value.
type should be a string with the data type of the values of the column. The type can be one of the following: 'string' 'number' 'boolean' 'date' 'datetime' 'timeofday'.
label should be a string with the label of the column. The column label is typically displayed as part of the visualization, for example as a column header in a table, or as a legend label in a pie chart. If not value is specified, an empty string is assigned.
id should be a string with a unique identifier for the column. If not value is specified, an empty string is assigned.
See also: getColumnId getColumnLabel getColumnType insertColumn
addRow() number Adds a new row to the data table, and returns the index of the new row. All the cells of the new row are assigned a null value.
addRows(numberOfRows) number Adds new rows to the data table, and returns the index of the last added row.
numberOfRows is the number of rows to add. All the cells of the new rows are assigned a null value.
See also: insertRows
getColumnId(columnIndex) string Returns the identifier of a given column specified by the column index. columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
For data tables that are retrieved by queries, the column identifier is set by the data source, and can be used to refer to columns when using the query language.
See also: Query.setQuery
getColumnLabel(columnIndex) string Returns the label of a given column specified by the column index. columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
The column label is typically displayed as part of the visualization. For example the column label can be displayees as a column header in a table, or as the legend label in a pie chart.
For data tables that are retrieved by queries, the column label is set by the data source, or by the label clause of the query language.
See also: setColumnLabel
getColumnPattern(columnIndex) string Returns the formatting pattern used to format the values of the specified column. columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
For data tables that are retrieved by queries, The column pattern is set by the data source, or by the format clause of the query language. An example of a pattern is '#,##0.00'. For more on patterns see the query language reference.
getColumnRange(columnIndex) Object Returns the minimal and maximal values of values in a specified column. The returned object has properties min and max. If the range has no values, min and max will contain null.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
getColumnType(columnIndex) string Returns the type of a given column specified by the column index. columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
The returned column type can be one of the following: 'string' 'number' 'boolean' 'date' 'datetime' 'timeofday'
getFormattedValue(rowIndex, columnIndex) string Returns the formatted value of the cell at the given row and column indices. rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method. columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
For more on formatting column values see the query language reference.
See also: setFormatedValue
getNumberOfColumns() number Returns the number of columns in the table.
getNumberOfRows() number Returns the number of rows in the table.
getProperty(rowIndex, columnIndex, name) Object Returns the value of a named property, or null if no such property is set for the specified cell.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
name is a string with the property name.
See also: setCell setProperties
getSortedRows(sortColumns) Array of row indices Sorts the rows, according to the specified sort columns, and returns an array of row indices (numbers). The DataTable is not modified by this method. The sortColumns argument is an array of objects, each object has a numeric property column which holds the column index to sort by, and an optional boolean property desc. If desc is set to true, the specific column will be sorted in descending order (the default is ascending order).
The returned value is an array of numbers, each number is an index of a DataTable row. Iterating on the DataTable rows by the order of the returned array will result in rows ordered by the specified sortColumns.
See also: sort

Example: To iterate on rows ordered by the third column, use: 

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}
getValue(rowIndex, columnIndex) object Returns the value of the cell at the given row and column indices.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
The type of the returned value depends on the column type (see getColumnType):
  • If the column type is 'string', the value is a string.
  • If the column type is 'number', the value is a number.
  • If the column type is 'boolean', the value is a boolean.
  • If the column type is 'date' or 'datetime', the value is a Date object.
  • If the column type is 'timeofday', the value is an array of four numbers: [hour, minute, second, millisenconds].
  • If the column value is a null value, regardless of the column type, the returned value is null.
insertColumn(columnIndex, type [,label [,id]]) none Inserts a new column to the data table, at the specifid index. All existing columns at or after the specified index are shifted to a higher index.
columnIndex is a number with the required index of the new column.
type should be a string with the data type of the values of the column. The type can be one of the following: 'string' 'number' 'boolean' 'date' 'datetime' 'timeofday'.
label should be a string with the label of the column. The column label is typically displayed as part of the visualization, for example as a column header in a table, or as a legend label in a pie chart. If no value is specified, an empty string is assigned.
id should be a string with a unique identifier for the column. If no value is specified, an empty string is assigned.
See also: addColumn
insertRows(rowIndex, numberOfRows) none Insert the specified number of rows at the specified row index.
rowIndex is a number with the required index of the first new row.
See also: addRows
removeColumn(columnIndex) none Removes the column at the specified index.
columnIndex should be a number with a valid column index.
See also: removeColumns
removeColumns(columnIndex, numberOfColumns) none Removes the specified number of columns starting from the column at the specified index.
numberOfColumns is the number of columns to remove.
columnIndex should be a number with a valid column index.
See also: removeColumn
removeRow(rowIndex) none Removes the row at the specified index.
rowIndex should be a number with a valid row index.
See also: removeRows
removeRows(rowIndex, numberOfRows) none Removes the specified number of rows starting from the row at the specified index.
numberOfRows is the number of rows to remove.
rowIndex should be a number with a valid row index.
See also: removeRow
setCell(rowIndex, columnIndex, value [, formattedValue [, properties]]) none Sets the content of a cell.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
value is the value assigned to the specified cell. The type of the returned value depends on the column type (see getColumnType):
  • If the column type is 'string', the value should be a string.
  • If the column type is 'number', the value should be a number.
  • If the column type is 'boolean', the value should be a boolean.
  • If the column type is 'date' or 'datetime', the value should be a Date object.
  • If the column type is 'timeofday', the value should be an array of four numbers: [hour, minute, second, millisenconds].
  • For any column type, the value can be set to null.
formattedValue is a string with the value formatted as a string. If null is specified, or if this parameter is omitted, the default formatting will be applied. The formatted value is typically used by visualizations to display value labels. For example the formatted value can appear as a label text within a pie chart.
properties is an optional Object (name/value map) with additional properties for this cell. If null is specified, or if this parameter is omitted, no additional properties are assigned to this cell.
setColumnLabel(columnIndex, label) none Sets the label of a column.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
label is a string with the label to assign to the column. The column label is typically displayed as part of the visualization. For example the column label can be displayees as a column header in a table, or as the legend label in a pie chart.
See also: getColumnLabel
setFormattedValue(rowIndex, columnIndex, formattedValue) none Sets the formatted value of a cell.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
formattedValue is a string with the value formatted for display.
See also: getFormatedValue
setProperty(rowIndex, columnIndex, name, value) none Sets the additional properties of a cell.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
name is a string with the property name.
value is a value of any type to assign to the specified named property of the specified cell.
See also: setCell setProperties setProperty
setProperties(rowIndex, columnIndex, properties) none Sets the additional properties of a cell.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
properties is an Object (name/value map) with additional properties for this cell. If null is specified, all additional properties of the cell will be removed.
See also: setCell setProperty getProperty
setValue(rowIndex, columnIndex, value) none Sets the value of a cell.
rowIndex should be a number greater than or equal to zero, and less than the number of rows as returned by the getNumberOfRows() method.
columnIndex should be a number greater than or equal to zero, and less than the number of columns as returned by the getNumberOfColumns() method.
value is the value assigned to the specified cell. The type of the returned value depends on the column type (see getColumnType):
  • If the column type is 'string', the value should be a string.
  • If the column type is 'number', the value should be a number.
  • If the column type is 'boolean', the value should be a boolean.
  • If the column type is 'date' or 'datetime', the value should be a Date object.
  • If the column type is 'timeofday', the value should be an array of four numbers: [hour, minute, second, millisenconds].
  • For any column type, the value can be set to null.
sort(sortColumns) none Sorts the rows, according to the specified sort columns. The DataTable is modified by this method.
The sortColumns argument is an array of objects, each object has a numeric property column which holds the column index to sort by, and an optional boolean property desc. If desc is set to true, the specific column will be sorted in descending order (the default is ascending order).
See also: getSortedRows
Example: To sort by the third column and then by the second column, use: data.sort([{column: 2}, {column: 1}]);

google.visualization.GadgetHelper

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

Constructors

google.visualization.GadgetHelper()

Methods

Method Return Value Description
createQueryFromPrefs(prefs) google.visualization.Query Static. Create a new instance of google.visualization.Query and set its properties according to values from the gadget preferences. The type of parameter prefs is _IG_Prefs
  1. Preference _table_query_url is used to set the Query data source URL.
  2. Preference _table_query_refresh_interval is used to set the Query refresh interval (in seconds).
validateResponse(response) boolean Static. Parameter response is of type google.visualization.QueryResponse. Returns true if the response contains data. Returns false if the query execution failed and the response does not contain data. If an error occured, this method displays an error message.

google.visualization.Query

Represents a query that is sent to a data source.

Constructors

google.visualization.Query(dataSourceUrl)

dataSourceUrl is of type string and is provided by the data source. 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'.

Methods

Method Return Value Description
setRefreshInterval(seconds) none Sets the query to automatically call the send method every specified duration (number of seconds), starting from the first explicit call to send. seconds is a number greater than or equal to zero.
If set to zero (the default), the query will not be automatically resent. This method, if used, should be called before calling the send method.
setTimeout(seconds) none Sets the number of seconds to wait for the data source to respond before raising a timeout error. seconds is a number greater than zero.
The default timeout is 30 seconds. This method, if used, should be called before calling the send method.
setQuery(string) none Sets the query string. The value of the string parameter should be a valid query.
This method, if used, should be called before calling the send method. Learn more about the Query language
send(callback) none Sends the query to the data source. callback should be a function that will be called when the data source responds. The callback function will receive a single parameter of type google.visualization.QueryResponse.

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

Method Return Value Description
getDataTable() DataTable Returns the data table as returned by the data source. Returns null if the query execution failed and no data was returned.
getDetailedMessage() string Returns a detailed error message for queries that failed. If the query execution was successful, this method returns an empty string. The message returned is a message that is intended for developers, and may contain technical information, for example 'Column {salary} does not exist'.
getMessage() string Returns a short error message for queries that failed. If the query execution was successful, this method returns an empty string. The message returned is a short message that is intended for end users, for example 'Invalid Query' or 'Access Denied'.
getReasons() Array of strings Returns an array of zero of more entries. Each entry is a short string with an error or warning code that was raised while executing the query. Possible codes:
  • access_denied The user does not have permissions to access the data source.
  • invalid_query The specified query has a syntax error.
  • data_truncated One or more data rows that match the query selection were not returned due to output size limits. (warning).
  • timeout The query did not respond within the expected time.
hasWarning() boolean Returns true if the query execution has any warning messages.
isError() boolean Returns true if the query execution failed, and the response does not contain any data table. Returns if the query execution was successful and the response contains a data table.