tzdata-javascript

Introduction

Standard JavaScript only supports two timezones, UTC and "the local timezone being used when the browser was started". On most platforms, it's not possible to change the local timezone of the browser without restarting the browser. In the cases where it is possible to change the local timezone without a browser restart, it has to be done at the operating system level and it's something a webpage can't request without the assistance of the user.
tzdata-javascript is a JavaScript library that enables the usage of multiple timezones on the same webpage without the assistance of the user.

World clock

Latest news

Usage

Load the library

Add the following HTML snippet to the <head>-section of your HTML page.

<script type="text/javascript" src="http://tzdata-javascript.org/tzdata-javascript.js">
</script>
		

Optionally change some settings

All settings are located under tzdata_javascript.settings.

<script type="text/javascript">
	/*
	 * The library works out of the box, but if you want to lessen the
	 * load of the library webserver (please do!) or if you want to
	 * use some "home-made" timezones, you can change the base URL of
	 * the zoneinfo files.
	 *
	 * The name of the requested timezone will be appended to the base
	 * URL, e.g.:
	 *
	 * http://example.com/zones/UTC
	 * http://example.com/zones/Europe/Copenhagen
	 *
	 * Default:		"http://zoneinfo.tzdata-javascript.org/zoneinfo/"
	 */
	tzdata_javascript.settings.baseURL="http://example.com/zones/";

	/*
	 * To avoid downloading the same timezones over and over again, the
	 * library will catch the various timezones, if "localStorage" is
	 * supported in the browser.
	 *
	 * This option tells the library whether or not it should try to
	 * use an already cached version of a timezone.
	 *
	 * You normally want to keep this "true", but if you suspect that
	 * your cached timezones has become corrupted, you can bypass the
	 * cache by changing this setting to "false". See also the next
	 * setting, which enables the (re-)caching of timezones.
	 *
	 * Default:		true
	 */
	tzdata_javascript.settings.localStorage.read=false;

	/*
	 * This option tells the library if it should cache the timezones
	 * as they are downloaded.
	 *
	 * You normally want this to happen, but localStorage is often
	 * limited to 2, 5 or 10 MB per site. If your site uses a lot of
	 * timezones, you might run out of localStorage, if you try to
	 * cache all of them.
	 *
	 * To give you an idea about how much space the timezones use, the
	 * 415 timezones used in the worldmap demo takes up just under 2 MB
	 * of space in total.
	 *
	 * Default:		true
	 */
	tzdata_javascript.settings.localStorage.write=false;
</script>
		

Load and use timezones

Finally load and use one or more timezones. The timezones are specified using the well known names from the Olson database and can be loaded either synchronous or asynchronous. It's often simpler to use the synchronous interface, but it should be avoided if you use a lot of timezones that ain't cached already.

<script type="text/javascript">
	var la=new tzdata_javascript.zoneinfo("America/Los_Angeles");
	var utc=new tzdata_javascript.zoneinfo("UTC");
	var cph=new tzdata_javascript.zoneinfo("Europe/Copenhagen");

	var now=new Date().valueOf();

	var localtime_la=la.localtime(now);
	var localtime_cph=cph.localtime(now);

	var difference=
		localtime_cph.ttinfo.offset-
		localtime_la.ttinfo.offset;

	alert(
		la.strftime("%+",now)+"\n"+
		utc.strftime("%+",now)+"\n"+
		cph.strftime("%+",now)+"\n"+
		"\n"+
		"Copenhagen is currently "+
		(difference/(60*1000))+
		" minutes ahead of Los Angeles"
	);
</script>
		

The asynchronous interface uses a call-back function.

<script type="text/javascript">
	new tzdata_javascript.zoneinfo(
		"UTC",
		function(timezone,zoneinfo)
		{
			var now=new Date().valueOf();

			alert(
				"In the '"+timezone+"' timezone, it's:\n"+
				zoneinfo.strftime("%+",now)
			);
		}
	);
</script>
		

The library has a "localtime" time zone, you can use if you want to use the same functions as you use for the regular time zones from the Olson database. Internally, the "localtime" time zone uses the standard getHours(), getMinutes() etc. functions of the Date object, completely bypassing the internal functions of the tzdata-javascript library.

Warning to users of Microsoft Windows

Since the "localtime" time zone uses the functions provided by the operating system, not the tzdata-javascript library, faults in the operating system might appear when you use the "localtime" time zone.
Microsoft is notoriously bad at keeping track of transition times between "standard time" and "summer time". Users of Microsoft Windows should therefore be warned against using the "localtime" time zone if they plan to use timestamps outside the current year.
Problems are VERY likely to show up! You have been warned!

As an example of the problem, let's compare the "Europe/London" timezone and what Microsoft Windows users located in the UK will see if they use the "localtime" time zone.
England ran an experiment in which they used GMT+1 the entire time between October 27th 1968 and October 31st 1971, i.e. "summer time" all the time.
Epoch (timestamp=0) is defined as "1970-01-01 T 00:00:00.000 UTC". Converted using the "Europe/London" timezone that's "1970-01-01 T 01:00:00.000 BTS". Note that the hours is "01" and the timezone abbreviation is "BST", i.e. "British Summer Time".
Unfortunately for Microsoft Windows users in the UK, timestamp=0 will be converted to "1970-01-01 T 00:00:00.000" if they use the "localtime" time zone. As you can see, the hours is "00", which is clearly wrong.
To confirm that this isn't a bug in the tzdata-javascript library, you can try running the following code on a Microsoft Windows machine located in England.

<script type="text/javascript">
	var epoch=new Date(0);

	alert("This should be 0, no matter where you are: "+epoch.getUTCHours());

	alert("This should be 1, if you're in England: "+epoch.getHours());
</script>
		

As you can see the code above does not use the tzdata-javascript library at all, so any errors in the output must come from somewhere else.
You're also more than welcome to run the code on Apple Mac OS, Linux or one of the BSDs. Neither of them should have any problems.

List of timezones

To get a list of (some of) the supported timezones, you can use this:

<script type="text/javascript">
	/*
	 * Synchronously:
	 */
	var timezones=tzdata_javascript.timezones();
	var timezone_array=Object.keys(timezones).sort();

	timezone_array.forEach(
		function(timezone)
		{
			console.log(timezone);
		}
	);

	/*
	 * Asynchronously:
	 */
	tzdata_javascript.timezones(
		function(timezones)
		{
			var timezone_array=Object.keys(timezones).sort();

			timezone_array.forEach(
				function(timezone)
				{
					console.log(timezone);
				}
			);
		}
	);
</script>
		

Due to the problem with Microsoft Windows mentioned above, "localtime" was removed from the default list of time zones on November 22nd 2013.
You can still use the "localtime" time zone, if you really want to, it just won't show up in any auto-generated list (e.g. drop-down menus) unless you actively take steps to make it so.

Features

Demos and examples

You're only allowed to use the library, if you load it from this site as specified under Load the library above.

The data files are created by a simple conversion from the official tzdata. Since the original data from tzdata are public domain, so are the converted data files.

Contact

If you have any questions about the library, you're welcome to contact us:

Donations

If you think this project is useful, you're more than welcome to donate:


[FSF Associate Member #5295] Valid XHTML 1.1 Valid CSS!