Hide

Library Loading Details

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

Basic Library Loading

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

  1. JSAPI: This is used to load the Google Charts library, the chart packages, and perform other important tasks. This must always be loaded first.
  2. Google Charts library: This library (sometimes called a "module") 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 packages: 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 drawing a pie chart using the basic loading technique:

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

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

    // Set a callback to run when the Google Charts 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 JSAPI

Google JSAPI is used to load other libraries, and is itself loaded by placing this at the top of your page:

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

Load Google Charts

The Google Charts 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 Charts 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 JSAPI include. Here is a description of each of the method parameters:

  • 'visualization' - Loads the Google Charts library.
  • '1' - Which version of the Google Charts library to load. 1 and 1.0 are always the current, stable versions 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 the Release Candidate documentation for information about 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 JSAPI), 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 Charts library and the corechart, geochart, and table packages:

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

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

Load Charts for 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 Charts API and the corechart package.
  google.load('visualization', '1', {'packages':['corechart'], 'language': 'ja'});

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

Follow this link for a live example.

Frozen Versions

When we push out new releases of Google Charts, some of the changes are big, like entirely new chart types, but other changes are small, like enhancements to the appearance or behavior of existing charts.

Many Google Chart creators fine-tune the look and feel of their charts until it's exactly what they want. Some of those users might feel more comfortable knowing that their charts will never change, regardless of what improvements we make in the future. For those users, we support Frozen Google Charts.

To load a frozen version, you must make some small changes in how you load the Google Charts packages. For example, here is the usual way of loading the stable version and drawing a chart:

<script type="text/javascript" 
        src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
    google.load('visualization', '1', {packages: ['corechart']});
    google.setOnLoadCallback(drawChart);
    ...
</script>

You'll need to change your code to be like this (changes highlighted in bold):

<script type="text/javascript" 
        src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
    google.charts.load('41', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

Note that this call to google.charts.load() lacks the "visualization" parameter. Only version '41' is supported at this time, which corresponds to the current stable release, and additional frozen versions will be announced as we push out each new stable release.

When you use a frozen version of Google Charts, all charts and features should work the same as for the stable version it was created from. But there are two minor, though important, limitations with loading frozen versions, which we expect to resolve in the near future.

  1. You can only call google.charts.load() one time. But you can list all the packages that you'll need in one call, so there's no need to make separate calls.
  2. If you're using a ChartWrapper, you must explicitly load all the packages you'll need, rather than relying on the ChartWrapper to automatically load them for you.

We expect that frozen versions will remain available indefinitely, though we may retire frozen versions that have security concerns. We will typically not provide support for frozen versions, except to suggest upgrading to newer versions.

Loading Non-Google Charts

Third-party charts can be loaded using additional <script> tags. Third-party charts are loaded from the visualization provider's web site; their documentation should provide specifics about how to load the appropriate library.

Warning: Google can't vouch for the security or accuracy of any visualization provided by others.

You can load any number or combination of Google 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 JSAPI-->
<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 Charts 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 JSAPI and Google Charts libraries.

<script type="text/javascript" src="https://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 JSAPI and Google Charts 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.

Advanced 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 JSAPI (and Google Charts 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 JSAPI, the Google Charts 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>