Google Charts

Library Loading Details

This page gives detailed information about loading the libraries necessary to put a chart on your page.

Contents

  1. Basic Library Loading
    1. Include the Google AJAX API
    2. Load the Google Visualization Library and Chart Libraries
    3. Loading Charts using a specific locale
    4. Loading Non-Google Charts
  2. Library Loading with ChartWrapper
  3. Enhanced Library Loading

Basic Library Loading

Your page will need to load at least three libraries to display a chart:

  1. Google AJAX API - This API is used to load the Google Visualization library, the visualization libraries, and perform other important tasks. This must always be loaded first; the next two libraries are loaded in a single call.
  2. Google Visualization library - This library includes common classes and methods used to create and handle visualizations, for example: DataTable to hold your data; Query for querying data providers; and error handlers to help you trap and display errors on the page.
  3. Individual chart libraries. - Each chart type is represented by a JavaScript class. The corechart library holds several common chart classes, including AreaChart, BarChart, and PieChart, but other charts require you to load specific libraries. Third-party third-party charts are loaded using individual <script> includes.

The following sections describe how to load these libraries in your page in the most basic way. More advanced methods are described below in Enhanced Library Loading. All three libraries can be loaded in a single call (Google charts only) when using the autoloading technique described below.

Here is an example of embedding a pie chart using the basic loading technique:

<head>
  <!--Load the AJAX API-->
  <script type="text/javascript" src="https://www.google.com/jsapi"></script>
  <script type="text/javascript">

    // Load the Visualization API and the piechart package.
    google.load('visualization', '1', {'packages':['corechart']});

    // Set a callback to run when the Google Visualization library is loaded.
    google.setOnLoadCallback(drawChart);

    // Callback that creates and populates a data table,
    // instantiates the pie chart, passes in the data and
    // draws it.
    function drawChart() {

    // Create our data table.
    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Topping');
    data.addColumn('number', 'Slices');
    data.addRows([
      ['Mushrooms', 3],
      ['Onions', 1],
    ]);

    // Instantiate and draw our chart, passing in some options.
    var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
    chart.draw(data, null);
  }
  </script>
</head>

Google AJAX API

The Google AJAX API is used to load other libraries and handle some core functionality such as event handling.

This library is loaded with the simple <script> tag shown here at the top of your page:

<!--Load the AJAX API-->
<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Load the Google Visualization Library and Google Chart Libraries

The Google Visualization library implements several classes and methods that you'll need to manipulate all charts, for example: the Query object for making data queries; the DataTable object that is used by a chart to hold its data; error handlers, and so on. Everything in this library is in the google.visualization namespace. You can see complete documentation of this library in the Reference section.

Load the Google Visualization library by calling google.load('visualization', '1.0', {'packages':[<<list-of-google-chart-libraries>>]}). It must be done in a separate <script> tag after the AJAX API include. Here is a description of each of the method parameters:

  • 'visualization' - Loads the Google Visualization library.
  • '1.0' - Which version of the Google Visualization library to load. 1.0 is always the current, stable version of the API; 1.1 is the experimental version. If you are running a big web site with a lot of critical charts, you might occasionally want to try the experimental version; see Release Candidate for information about any experimental versions.
  • <<list-of-google-chart-libraries>> - A list of Google-authored chart libraries to load. Each chart's documentation describes the package name to use in the loader. The corechart package holds several common charts, including area chart, bar chart, and pie chart.

You must wait until all the chart libraries are loaded before you can begin to code against them. After calling google.load(), call google.setOnloadCallback(your_callback_handler) (defined in the Google AJAX API), passing in the name of a function to call when all the Google libraries are finished loading. In this callback function, you can start to code your chart.

Here is an example of loading the Google Visualization library and the corechart, geochart, and table packages.:

<script type="text/javascript">
  // Load the Visualization API and the piechart package.
  google.load('visualization', '1', {'packages':['corechart','geochart','table']});

  // Set a callback to run when the Google Visualization library is loaded.
  google.setOnLoadCallback(drawChart);
  function drawChart() {
    // Everything is loaded; draw the chart here...
    ...
  }
<script>

Loading Charts using a specific locale

By default, the Google Chart libraries are loaded with the locale specified by the browser. You can override this default by explicitly specifying a locale in the loading parameters. Specifying a locale lets you determine how numbers and dates are formatted in the chart.

Here is an example of how to load a pie chart formatted for the Japanese locale. Note that the pie chart is included in the corechart package.

<script type="text/javascript">
  // Load the Visualization API and the corechart package.
  google.load('visualization', '1', {'packages':['corechart'], 'language': 'ja'});

  // Set a callback to run when the Google Visualization library is loaded.
  google.setOnLoadCallback(drawChart);
  geochart, and table packages
  function drawChart() {
    // Everything is loaded; draw the chart here...
    ...
  }
<script>

Follow this link for a live example.

Loading Non-Google Charts

Third-party charts are loaded using additional <script> tags. Third-party charts are loaded from the visualization provider's web site the chart's documentation should give any specifics about how to load the appropriate library.

Warning: Google highly discourages using any visualization not listed on the Google web site.

You can load any number or combination of Google and/or third-party charts on the same page. Note that you only need to load a library once, no matter how many times it's used on the page (that is, even if you have five pie charts on the page, you need only load the library once). Here is how to load either type of chart:

Here's an example of loading both a Google chart and a third-party chart:

<!--Load the AJAX API-->
<script type="text/javascript" src="https://www.google.com/jsapi"></script>

<!--Load a third-party visualization-->
<script type="text/javascript" src="http://www.example.com/time_travel_visualization.js"></script>
<script type="text/javascript">

  // Load the Visualization API, core charts, table and geo charts.
  // is included in the corechart package.
  google.load('visualization', '1.0', {'packages':['corechart','table','geochart']});
  google.setOnLoadCallback(drawChart);
...
</script>

Library Loading with ChartWrapper

When using the ChartWrapper class, you do not need to explicitly load any chart libraries; the ChartWrapper loads them for you. You need to load only the Google JSAPI and Google Visualization libraries.

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load('visualization', '1',null); // No 'packages' section.

  google.setOnLoadCallback(drawVisualization);

  function drawVisualization() {

    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>

Combined with the autoloader syntax, you can combine the JSAPI and Google Visualization library loading into a single step, as shown here, but note that you must still have two separate <script> tags:

 <script type="text/javascript"
    src='https://www.google.com/jsapi?autoload={"modules":[{"name":"visualization","version":"1"}]}'>
 </script>
 <script type="text/javascript">
   google.setOnLoadCallback(drawVisualization);

   function drawVisualization() {
     // Define the chart using setters:
     var wrap = new google.visualization.ChartWrapper();
     wrap.setChartType('LineChart');
     wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
     wrap.setContainerId('visualization');
     wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
     wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
     wrap.draw();
   }
</script>

If you are using third-party charts, you still must include any additional <script> tags required by those charts.

Enhanced Library Loading

If you want to load the libraries only under certain conditions (for example, when the user takes a certain action), or if you have several visualizations on a page and that is causing a slow load time, there are some tricks you can do to speed things up.

  • Dynamic Loading - You can load the AJAX API (and Google visualization libraries) after the page has loaded by using dynamic loading. For example, if you only want to show a visualization if a user clicks a tab on the page. Note that the loader keeps track of what has already been loaded, so if you try loading the same visualization package multiple times it won't bother reloading it each time.
  • Autoloading - If load time for your page is very important, you can eliminate a round-trip request to the Google server by using autoloading to load the Google AJAX API, the Google Visualization library, and all Google-authored visualizations. This saves the browser one round-trip call to Google, which can speed up pages a bit for the user. See the linked section for details. Here is an example <script> tag that loads the google.visualization and corechart libraries in a single call. Be sure to escape any quotation marks in the URL, or else use a different type of quotation mark to surround the URL string (single versus double) than is used within the URL string.
<script type="text/javascript"
  src='https://www.google.com/jsapi?autoload={"modules":[{"name":"visualization","version":"1","packages":["corechart","table"]}]}'>
</script>
<script type="text/javascript">
  google.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    ...
  }
</script>

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.