Overview

Important: In JavaScript Date objects, months are indexed starting at zero and go up
through eleven, with January being month 0 and December being month 11.

Dates and Times Using the Date Constructor

Dates Using the Date Constructor

To create a new Date object, you call the Date() constructor with the
new keyword, with arguments to specify components of the date. These arguments
take the form of several numbers corresponding to the different properties of your date.

new Date(Year, Month, Day, Hours, Minutes, Seconds, Milliseconds)

When using the Date constructor with the date data type, you only need to specify
the Year, Month, and Day.

The Date constructor can also take the form: new Date(Milliseconds), where
Milliseconds is the distance in milliseconds of the desired date from
January 1, 1970 00:00:00 UTC. For dates and times prior to that date, a negative number of
Milliseconds would be given.

Using the Date constructor is useful when manually constructing your DataTable
using the addColumn(), addRow(), and addRows() methods,
as well as the arrayToDataTable() method. However, if using JSON to specify data,
the string representation needs to be used.

The JavaScript Date constructor can also accept a string representation of the date as
an argument. This string can take several different forms. The most reliable forms conform to
either the
RFC 2822 specification or the
ISO 8601 specification. The formats for these are:

Warning: The string representation in the Date constructor may be parsed differently by
different browsers and different versions of browsers, thus returning different dates for the
same string. As such, it is not recommended to pass in strings to the Date
constructor. Instead, it is encouraged to only use numbers for the Date constructor's arguments.

The timeline below shows the Super Bowl champion of each NFL season since the year 2000.

[This section requires a browser that supports JavaScript and iframes.]

Below is the code for creating this timeline. Note the use of the new Date()
constructors, and the numbers given for each date, using 0-based months as mentioned earlier.

Datetimes Using the Date Constructor

The DataTable datetime column data type uses the same Date constructor as
the date data type, but now uses all of the arguments to fill out the time.

Alternatively, a string representation of datetime can also be passed into the
Date constructor. A string representation of datetime consists of adding the
hours, minutes, and seconds, in addition to the 4-digit timezone offset (e.g. Pacific Standard
Time (PST) is -0800). For the RFC 2822 spec, the time and timezone are added with spaces
between the date and the time, and the time and the timezone. In the ISO 8601 spec, there are
no spaces, instead the date is followed by an uppercase "T" to denote a time component. There
is also no space between the time and the timezone offset. The full datetime date
string for December 6, 2014 at 10:30am PST would be:

RFC 2822 — Dec 6, 2014 10:30:00 -0800.

ISO 8601 — 2014-12-06T10:30:00-0800.

Warning: Again, the string representation may be parsed differently by different
browsers/versions. Notably, when dealing with time and timezones, there are differences in
whether the datetime is returned with a UTC (GMT) timezone, or is offset and returned in local
time. This is another reason why the use of datetime strings is not recommended.

The below timeline breaks down an average day, using the datetime data type.

[This section requires a browser that supports JavaScript and iframes.]

Dates, Times, and Timezones

Using the Date constructor, either for date or datetime, will return
the desired date or datetime in the timezone set by the user's browser.
Setting your Date object to a specific timezone can be achieved in a
few ways. First, Google Charts provides a
Date Formatter in which you can
specify a timeZone. This will provide a formatted value for each of your
date and datetime values in your DataTable. You can also pass in a
string as your argument to the new Date()
constructor, or you can wrap your arguments in the Date.UTC() method, such as:

This will set a Date object to the specified date and time in the UTC (GMT) timezone. From
there you can calculate the desired offset for timezone and set your dates and times as desired.

Dates and Times Using the Date String Representation

When serializing data using the JavaScript
DataTable object literal notation
to build your DataTable, the new Date() constructor cannot be used. Instead,
Google Charts provides a Date string representation that allows your date or
datetime to be serialized and parsed properly when creating a DataTable. This Date
string format simply drops the new keyword and wraps the remaining expression in
quotation marks:

"Date(Year, Month, Day, Hours, Minutes, Seconds, Milliseconds)"

Important: When using this Date String Represenation, as when using the
new Date() constructor, months are indexed starting at zero (January is month 0,
December is month 11).

Below is the same Super Bowl timeline from before, but now using the JavaScript object literal
notation and the Date string format.

[This section requires a browser that supports JavaScript and iframes.]

This format can also be used in the arrayToDataTable() method, provided that in
the first array, where column labels are specified, you declare the necessary column as being of
type: 'date' or type: 'datetime'.

Working With Timeofday

The DataTable timeofday column data type takes an array of either 3 or 4 numbers,
representing hours, minutes, seconds, and optionally milliseconds, respectively. Using
timeofday is different than using date and datetime in
that the values are not specific to a date, whereas date and datetime
always specify a date.

For example, the
time 8:30am would be: [8, 30, 0, 0], with the 4th value being optional
([8, 30, 0] would output the same timeofday value).

[This section requires a browser that supports JavaScript and iframes.]

Formatting Axis, Gridline, and Tick Labels

When working with dates, datetime, and timeofday, it may be desired to format the axis labels,
gridline labels, or tick labels a certain way. This can be achieved in a few ways.

First, you can use the hAxis.format or vAxis.format option. This
option applies when the gridlines.count option is omitted, in which case the chart
defaults to a count of 5, as well as when it is set to a number other than -1. This allows you
to specify a format string, where you use placeholder letters for different parts of your
date/datetime/timeofday. See the
date formatter reference,
specifically the pattern section for more information on the placeholders and
how they work.

[This section requires a browser that supports JavaScript and iframes.]

You can also provide formatting rules for specific units of date and time values by including a
units option under gridlines and minorGridlines for both
axes. This option will only be used if the gridlines.count option is set to -1.

The gridlines.units option is an object, where you specify the format for the
different aspects of date/datetime/timeofday for the computed gridline, and your chart will
compute the gridlines based on the first format which fits the space for the gridline label.
You can set the formats for years, months, days, hours, minutes, seconds, and milliseconds.

The format option accepts an array of string formats, and will use them in order until a format
fits the label area. For this reason, it is recommended to list the formats in order from
longest to shortest. The string formats use the same patterns as the
date formatter reference
mentioned earlier.

[This section requires a browser that supports JavaScript and iframes.]

Note that in the above chart, when changing the view window, the format for the
hours unit changes, given that hours switch from minor to major gridlines,
and the format in the options changes with them. Also, note that minorGridlines are using the
second, shorter formats, as the first formats do not fit the space in each instance.