English | Site Directory

Google Visualization API

Frequently Asked Questions

Getting Started

What is the Google Visualization API?
The Google Visualization API allows you to create visualizations and reporting applications over structured data and helps integrate these directly into your website or on a Gadget.
What can I do with the Visualization API?
With the Google Visualization API, you can access structured data--created locally in your browser or retrieved from supported data sources in a simple tabular format. You can also implement your own data source as Visualization API data source and enable any Visualization-compliant visualization and/or application to access your data. The format is amenable to use by reporting, analysis or visualization applications. You can thus visualize the data and/or add new functionality to applications, such as Google Spreadsheets.
Where can I find documentation for the Visualization API?
You can find the developer guide and all other related documentation at http://code.google.com/apis/visualization/documentation.
I have a question related to embedding a Visualization gadget on Google Spreadsheets. Where do I go for help?
For specific questions related to Google Spreadsheets we suggest you first check the Spreadsheet Integration section. You can also refer to the help pages for Google Spreadsheets. If you are not able to find an answer in either of these places, the best way is to post your question on the Visualization discussion group. Google employees also participate in the group and pop in from time to time to answer developer questions.
How do I embed a Visualization gadget on my website?

If you have your gadget on a Google Spreadsheet, open the gadget menu, and select 'Publish gadget'. Paste the provided URL into your web page.

If you have your gadget on iGoogle, open the gadget preferences, select 'Share this gadget', select 'copy and paste a link to this gadget' and check the 'Send my settings for this gadget'. Paste the provided URL into your web page.

On any other web page, if you have acces to the source code, paste the XML of the gadget wrapped inside an iframe on the page. Be sure to set the data source preference in the XML.

How do I create a new Visualization?
The best way to get started is to read the Developers Guide, and the Creating Visualizations section.
What is a Data Source URL?
A Data Source URL is the unique URL identifier of a Visualization API data source. A data source URL may also include Visualization Query Language parameters. In this case a query (such as sorting, grouping, etc) is performed on the data source prior to fetching the data. When accessing a Google Visualization data source, such as Google Spreadsheets, from a Visualization gadget, you need to set the gadget's data source URL user pref to point to the correct data source. For more information refer to the Using Visualization Gadgets section. For using Visualization gadgets on Google Spreadsheets refer to the Spreadsheet Integration section of the documentation.
How do I create a new Visualization gadget?
The best way to get started is to first get familiar with the Developers Guide, and then read the Gadget Extensions section and start coding.
Where can I find example code of Visualization apps and/or gadgets using the Visualization API?
You can find example code at the Visualization API example code documentation.
Can a Flash application access the Visualization API?
Absolutely. The Visualization API uses a JavaScript API, but there are libraries that enable Flash apps to connect with JS code. One such library you may find useful can be found at http://code.google.com/p/swfobject. See below for some development issues affecting Flash.
 
Where can I find a sample Visualization data source implementation?
See the Visualization API Python sample page for explanations and example code.
How do I implement a data source?
Read the sections on using and creating a visualization, to learn how visualizations work, then read Implementing a Data Source to learn how to create a data source.
Can I access a visualization from a Java application?
Yes. The Google Visualization Library for the Google Web Toolkit (GWT) allows you to access the API compliant visualizations from Java code compiled with the GWT compiler and to write Visualization API compliant visualizations in Java using the GWT complier. The release candidate library also supports the Visualization API event model.
Can I access a visualization from an application written with the Google Web Toolkit (GWT) compiler?
Yes. The Google Visualization Library for the Google Web Toolkit (GWT) allows you to access the API compliant visualizations from Java code compiled with the GWT compiler and to write Visualization API compliant visualizations in Java using the GWT complier. The release candidate library also supports the Visualization API event model.
I have a different question/problem, who do I contact to get more information?
Please post your question in the Google Visualization API discussion group to get help from the Visualization developer community. The Visualization team also participates in this group to answer questions.

Using the API

What is the difference between the Google Chart API and the Google Visualization API?

The Chart API provides a simple way to create image charts of various kinds by sending a formatted URL that includes both the data and chart configuration options to a Google server. The Chart API includes a closed set of charts with various options. The Chart API datasets are limited to the size of a URL (roughly 2K).

The Visualization API provides a way to connect visualizations and data sources over the web and to publish them:

  • The Visualization API provides a JS API and a Gadget API to access visualizations.
  • Its gallery of visualizations includes Google-created visualizations, but is also open to any third party to create their own Visualization API-compliant visualizations.
  • Visualization API visualizations and charts can be anything that can be rendered by a browser. This includes images, JS, vector-graphics, Flash, etc.
  • A considerable number of Chart API charts are accessible through the Visualization API, although some of their configuration options may not be available.
  • The API also provides a documented wire protocol and a way for anyone to expose their data sources to any of the APIs visualizations.
  • The API has a defined event model that allows visualizations to throw and receive events and thus communicate with their host page and/or other visualizations on the page.
    • What data sources can I access using the Visualization API?
    With the Visualization API you can access data locally from your browser by creating the API's standard DataTable format, or access any data source that supports the API. Well-known applications that already support the API are Google Spreadsheets and Salesforce.com on their Force.com developer platform. You may also implement your own data as a Visualization data source.
    I created a Visualization application using the Visualization API, can I make that app into a Gadget?
    Absolutely. To wrap your application as a gadget refer to the Gadget Extensions section of the developer guide.
    My application expects the data it receives to be in a specific format. How do I handle exceptions?
    You can use the getNumberOfColumns() and getColumnType() methods of class google.visualization.DataTable to test that the data you get matches what you expect, and issue an error message for mismatches.
    What are the differences between Gadget Visualizations and JS Visualizations?
    The major differences are:
    • Gadgets run in separate iframes and therefore are safe to place on any webpage, even if they are developed by 3rd parties. They are also easily publishable and shareable on Gadget containers, such as iGoogle, etc. However, they require more server calls and it is very difficult to create inter-gadget communication.
    • JS code runs directly on the webpage and is therefore less "safe". However, their advantage is in lower latencies and in the ability to access the Gviz Event Model. With these events, one can easily create dashboards in which one visualization is tied to others on the page. This example shows how a click on an item in the table or map changes the other visualization's focus.
    Which visualizations are available as Gadgets and which as JS Visualizations?
    We try to provide all visualizations in both flavors, and this is what we recommend developers to do, as it is generally easy developer visualizations for the JS API and then to wrap them as Gadgets.
    How do I override the default exception and error handling in Gadgets?

    If you call validateResponse() of class google.visualization.GadgetHelper, the default error message handling will check for errors and send a message to the user in case of an error.

    If you do not want to use the default error handling, you can check for errors yourself by calling the isError() method of the google.visualization.QueryResponse class and issuing your own message for the error. Use methods getMessage() and getDetailedMessage() to obtain more information about the error.

    My visualization is not showing up on the page. What is the problem?

    There may be several reasons causing your visualization not to show.

    Is it safe to embed a visualization in my web site?

    Running third party code directly on your web site poses inherent risks. Gadgets run in a separate iframe, and are generally safer than JavaScript embedded in your web page. Google makes no promises or representations about the gadgets' and applications' performance, quality, security, or content. Visualization applications and gadgets that do not comply with the Google Visualization API Terms of Service may be removed from the galleries.

    Why does my Flash-based visualization not work during development?
    Because of Flash security settings, Flash-based visualizations might not work correctly when accessed from a file location in the browser (e.g., file:///c:/webhost/myhost/myviz.html) rather than from a web server URL (e.g., http://www.myhost.com/myviz.html). This is typically a testing issue only; the issue is not a problem when you access the visualization from an http:// address. You can overcome this issue as described on the Macromedia web site.

    Google Visualization Program Policy

    What is the Google Visualization Program Policy?

    As described in the Terms of Service, we may decline to include and display content that violates our program policy by displaying or linking to:

    • Illegal content.
    • Invasions of personal privacy.
    • Pornography or obscenity.
    • Content, such as malicious code, that interferes with or is harmful to a user's computer or the functioning of the host web page.
    • Promotions of hate or incitement of violence.
    • Violations of copyright. Please see our DMCA policy for more information.
    • Violations of trademark.
    • Impersonations of third parties.

    Developers that create visualizations that collect data, agree to maintain and link to a legally adequate privacy policy. Additionally, we require developers to ensure that their visualization is secure, and to maintain their gadget or application as long as it resides in the visualization directory.

    These policies may be revised from time to time without notice.

    Is the Google Visualization API available for commercial use?
    Yes. For the fine print please refer to the Google Visualization API Terms of Service.
    Can I use the Google Visualization API to create client-side software?
    Currently we do not allow developers to use the Visualization API to create client-side software. You may only use the Visualization API through the interface provided. For the fine print please refer to the Google Visualization API Terms of Service.
    What personal information can I collect through a Visualization gadget or visualization?
    You may not store any personal information in the gadget or visualization.  You may not collect sensitive personal information such as credit card numbers and social security numbers through a gadget or visualization.
    Violations of the program policies.
    Violations of these Program Policies can result in the disabling of your gadget or visualization, removal of your gadget or visualization, being blacklisted from uploading future gadgets or visualizations, termination of your Google accounts and/or deletion of all your gadgets and visualizations.

    Becoming Active in the Community

    How can I share my Visualization application or gadget with others?
    Start by placing your visualization on the Visualization Gallery and your gadgets on the Gadget content directory and the API's Gadget Gallery. You can link back to your site and provide your source code if you wish. Get involved in our discussion group and get the community's feedback.
    The Visualization Gallery is a listing of applications that use the Visualization API. It provides a central location for the Visualization developer community to share Visualization applications.
    What is the Visualization Gadget Gallery?
    The Visualization Gadget Gallery is a listing of gadgets that use the Visualization API. It provides a central location for the Visualization developer community to share Visualization gadgets.
    How do I get my Visualization application on the Visualization or Gadget Gallery?
    Submit your visualization to the Visualization Gallery and your gadget to the Visualization Gadget Gallery
    What is the Gadget content directory?
    The Gadget content directory is a listing of Gadgets that can be added to iGoogle or other web pages. It provides a central location for users to find new gadgets to add to their pages. Most of the gadgets in the content directory were written by other companies and by Google's users.
    How do I submit my Visualization gadget to the Gadget content directory?
    Any submission to the Visualization Gadget Gallery will also auto-submit your gadget to the Gadget content directory.
    Why would I want to submit a gadget to both the API's Gadget Gallery and the Gadget content directory?
    The Gadget content directory provides the widest consumer audience for your gadget, while the Visualization Gadget Gallery provides a targeted audience of visualization developers. With both galleries you cover your two target audience groups and get both wide and in-depth market reach. Any submission to the Visualization Gadget Gallery will also auto-submit your gadget to the Gadget content directory.
    How do I make my Visualization gadget more discoverable?

    There are various ways you can promote your gadget and help other users discover it. Getting more people to use your gadgets is rewarding and helps increase your gadget's ranking in the Gadget content directory. Here's a few recommended ways to get started:

    How can I promote my Visualization data source?
    Post your implementation on the Visualization Group. If we like it, we might even mention it ourselves.