My favorites | English | Sign in

Google Visualization API

Visualization: Annotated Time Line

  1. Overview
  2. Example
  3. Loading
  4. Data Format
  5. Configuration Options
  6. Methods
  7. Events
  8. Data Policy
  9. Localization
  10. Notes

Overview

An interactive time series line chart with optional annotations. The chart is rendered within the browser using Flash.

By: Google

Example

<html>
  <head>
    <script type='text/javascript' src='http://www.google.com/jsapi'></script>
    <script type='text/javascript'>
      google.load('visualization', '1', {'packages':['annotatedtimeline']});
      google.setOnLoadCallback(drawChart);
      function drawChart() {
        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Date');
        data.addColumn('number', 'Sold Pencils');
        data.addColumn('string', 'title1');
        data.addColumn('string', 'text1');
        data.addColumn('number', 'Sold Pens');
        data.addColumn('string', 'title2');
        data.addColumn('string', 'text2');
        data.addRows(6);
        data.setValue(0, 0, new Date(2008, 1 ,1));
        data.setValue(0, 1, 30000);
        data.setValue(0, 4, 40645);
        data.setValue(1, 0, new Date(2008, 1 ,2));
        data.setValue(1, 1, 14045);
        data.setValue(1, 4, 20374);
        data.setValue(2, 0, new Date(2008, 1 ,3));
        data.setValue(2, 1, 55022);
        data.setValue(2, 4, 50766);
        data.setValue(3, 0, new Date(2008, 1 ,4));
        data.setValue(3, 1, 75284);
        data.setValue(3, 4, 14334);
        data.setValue(3, 5, 'Out of Stock');
        data.setValue(3, 6, 'Ran out of stock on pens at 4pm');
        data.setValue(4, 0, new Date(2008, 1 ,5));
        data.setValue(4, 1, 41476);
        data.setValue(4, 2, 'Bought Pens');
        data.setValue(4, 3, 'Bought 200k pens');
        data.setValue(4, 4, 66467);
        data.setValue(5, 0, new Date(2008, 1 ,6));
        data.setValue(5, 1, 33322);
        data.setValue(5, 4, 39463);

        var chart = new google.visualization.AnnotatedTimeLine(document.getElementById('chart_div'));
        chart.draw(data, {displayAnnotations: true});
      }
    </script>
  </head>

  <body>
    <div id='chart_div' style='width: 700px; height: 240px;'></div>
  </body>
</html>

Get started quickly with an Interactive Code Sample you can edit and save.

Loading

The google.load package name is "annotatedtimeline"

  google.load("visualization", "1", {packages: ['annotatedtimeline']});

The visualization's class name is google.visualization.AnnotatedTimeLine

  var visualization = new google.visualization.AnnotatedTimeLine(container);

Data Format

The first column is of type date or datetime, and specifies the date points along the bottom of the chart. If this column is of type date (and not datetime) then the smallest time resolution on the X axis will be one day.

There can then be multiple columns to describe as many data lines (called series) as you want in the chart. Each series is described by a set of one to three columns, described here (they must be grouped in the order given):

  • Value column - [Required number] This column describes the values of a series; each row is a data point at the date in column zero. The title of this column is displayed for the line on the chart.
  • Annotation column - [Optional string] If a string column follows the numeric column, and the displayAnnotations options is true, this column holds captions for the corresponding data points in this series. You do not need an entry for every cell in this column; blank cells mean no caption for that data point. The column title is not used in your chart.
  • Annotation text column - [Optional string] If a second string column exists for this series, any cell values will be used as extended annotations for the caption of the same data point. You can use HTML tags, if you set allowHtml to true; there is essentially no size limit, but note that excessively long entries might overflow the display section. You must set the option displayAnnotations to true to use this column. You are not required to have this column even if you have an annotation column. The column title is not used in your chart.

Configuration Options

Name Type Default Description
allowHtml boolean false If set to true, any annotation text that includes HTML tags will be rendered as HTML.
allValuesSuffix string none A suffix to be added to all values in the scales and the legend.
annotationsWidth number 25 The width (in percent) of the annotations area, out of the entire chart area. Must be a number in the range 5-80.
colors Array of strings Default colors The colors to use for the chart lines and labels. An array of strings. Each element is a string in a valid HTML color format. For example 'red' or '#00cc00'.
dateFormat string Either 'MMMM dd, yyyy' or 'HH:mm MMMM dd, yyyy', depending on the type of the first column (date, or datetime, respectively). The format used to display the date information in the top right corner. The format of this field is as specified by the java SimpleDateFormat class.
displayAnnotations boolean false If set to true, the chart will show annotations on top of selected values. When this option is set to true, after every numeric column, two optional annotation string columns can be added, one for the annotation title and one for the annotation text.
displayAnnotationsFilter boolean false If set to true, the chart will display a filter contol to filter annotations. Use this option when there are many annotations.
displayExactValues boolean false Whether to display a shortened, rounded version of the values on the top of the graph, to save space; false indicates that it may. For example, if set to false, 56123.45 might be displayed as 56.12k.
displayRangeSelector boolean true Whether to show the zoom range selection area (the area at the bottom of the chart), where false means no.
displayZoomButtons boolean true Whether to show the zoom buttons, where false means no.
fill number 0 A number from 0—100 (inclusive) specifying the alpha of the fill of the line graph. 100 means 100% opaque fill, 0 means no fill at all.
legendPosition string 'sameRow' Whether to put the colored legend on the same row with the zoom buttons and the date ('sameRow'), or on a new row ('newRow').
max number automatic The maximum value to show on the Y axis. If the maximum data point exceeds this value, this setting will be ignored, and the chart will be adjusted to show the next major tick mark above the maximum data point.
min number automatic The minimum value to show on the Y axis. If the minimum data point is less than this value, this setting will be ignored, and the chart will be adjusted to show the next major tick mark below the minimum data point.
numberFormats String, or a map of number:String pairs automatic

Specifies the number format patterns to be used to format the values at the top of the graph.

The patterns should be in the format as specified by the java DecimalFormat class.

  • If not specified, the default format pattern is used.
  • If a single string pattern is specified, it is used for all of the values.
  • If a map is specified, the keys are (zero-based) indexes of series, and the values are the patterns to be used to format the specified series.
    You are not required to include a format for every series on teh chart; any unspecified series will use teh default format.

If this option is specified, the displayExactValues option is ignored.
scaleColumns Array of numbers Automatic

Specifies which values to show on the Y axis tick marks in the graph. The default is to have a single scale on the right side, which applies to both series; but you can have different sides of the graph scaled to different series values.

This option takes an array of zero to three numbers specifying the (zero-based) index of the series to use as the scale value. Where these values are shown depends on how many values you include in your array:

  • If you specify an empty array, the chart will not show Y values next to the tick marks.
  • If you specify one value, the scale of the indicated series will be displayed on the right side of the chart only.
  • If you specify two values, a the scale for the second series will be added to the right of the chart.
  • If you specify three values, a scale for the third series will be added to the middle of the chart.
  • Any values after the third in the array will be ignored.

When displaying more than one scale, it is advisable to set the scaleType option to either 'allfixed' or 'allmaximize'.

scaleType string 'fixed'

Sets the maximum and minimum values shown. The following options are available:

  • 'maximize' - The Y axis range will span the minimum to the maximum values of all series in the graph.
  • 'fixed' - The Y axis range will span zero to the maximum value of all series in the graph.
  • 'allmaximize' - Same as 'maximize,' but used when multiple scales are displayed. This setting adjusts each scale to the series to which it applies (use this in conjunction with scaleColumns).
  • 'allfixed' - Same as 'fixed,' but used when multiple scales are displayed. This setting adjusts each scale to the series to which it applies (use this in conjunction with scaleColumns).
thickness number 0 A number from 0—10 (inclusive) specifying the thickness of the lines, where 0 is the thinnest.
wmode string 'window' The Window Mode (wmode) parameter for the Flash chart. Available values are: 'opaque', 'window' or 'transparent'.
zoomEndTime Date none Sets the end date/time of the selected zoom range.
zoomStartTime Date none Sets the start date/time of the selected zoom range.

Methods

Method Return Type Description
draw(data, options) none Draws the chart.
getSelection() Array of selection elements Standard getSelection() implementation. Selected elements are cell elements. Only one cell can be selected at a time by the user.
getVisibleChartRange() An object with start and end properties Returns a an object with start and end properties, which each one of them is a Date object, representing the current time selection.
hideDataColumns(columnIndexes) none Hides the specified data series from the chart. Accepts one parameter which can be a number or an array of numbers, in which 0 refers to the first data series, and so on.
setVisibleChartRange(start, end) none Sets the visible range (zoom) to the specified range. Accepts two parameters of type Date that represent the first and last times of the wanted selected visible range.
showDataColumns(columnIndexes) none Shows the specified data series from the chart, after they were hidden using hideDataColumns method. Accepts one parameter which can be a number or an array of numbers, in which 0 refers to the first data series, and so on.

Events

Name Description Properties
rangechange Zoom range changed. Fired after the user modified the visible time range but not after a call to setVisibleChartRange method.
Note: It is advised not to use the event properties, but rather get them by calling getVisibleChartRange method.
  • start: Date. The start time of the zoom range.
  • end: Date. The end time of the zoom range.
ready The chart is ready for external method calls. If you want to interact with the chart, and call methods after you draw it, you should set up a listener for this event before you call the draw method, and call them only after the event was fired None
select When the user clicks on an annotation flag (marker), the corresponding cell in the data table is selected. The visualization then fires this event. None

Note: Because of certain limitations, events might not be thrown if you are accessing the page in your browser as a file (e.g., "file://") rather than from a server (e.g., "http://www").

Data Policy

All code and data are processed and rendered in the browser. No data is sent to any server.

Localization

This visualization has been localized for the following locales: ca, da, de, en, en_GB, en_IE, es, es_419, fi, fr, id, in, is, it, nl, no, pt, pt_BR, pt_PT, sv, zh_CN, zh_TW, ja, ko.

Notes

Because of Flash security settings, this (and all 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. You can overcome this issue as described on the Macromedia web site.