Time Zones
iCal Library

The convenient way to directly access the most recent official time zone information for iCalendar files with JavaScript/Typescript.

🗓️ iCal Time zone information for JavaScript

This tool converts the most recent IANA (formerly Olson) time zone database files into VTIMEZONE blocks, which are compatible with the iCalendar specification (RFC2445).

It is optimized to be easily used in every JavaScript or Typescript project; may it be VanillaJS, React, Angular, Vue, Svelte, or based on any other framework or library.

📦 How to install

Simply install the package via npm:

npm install timezones-ical-library

... and import it for commonJS approaches with:

const tzLib = require('timezones-ical-library');

... or (preferred) with ES support:

import { tzlib_get_ical_block, tzlib_get_offset, tzlib_get_timezones } from 'timezones-ical-library';

⚙️ How to use

Get time zones

Use tzlib_get_timezones() to retrieve a list of all available time zone strings. You can pass true to retrieve a JSON formatted string instead of an array.

Get the iCal time zone block

Use the tzlib_get_ical_block(tzName) function to return the proper iCal VTIMEZONE block for a given time zone string (tzName). Again, pass true to retrieve a JSON formatted string instead of an array (not recommended).
You will receive an array, holding the VTIMEZONE block first, and the TZID line (additionally) second. The latter one is needed for any further time statement.
Include this into your further iCal data to come up with a complete ics file.

A final constellation could look like this:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-// github.com/add2cal/add-to-calendar-button //EN
CALSCALE:GREGORIAN
BEGIN:VTIMEZONE
TZID:America/New_York
LAST-MODIFIED:20220824T133813Z
X-LIC-LOCATION:America/New_York
BEGIN:DAYLIGHT
TZNAME:EDT
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
DTSTART:19700308T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
END:DAYLIGHT
BEGIN:STANDARD
TZNAME:EST
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
DTSTART:19701101T020000
RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
UID:2022-08-30T19:29:38.618Z@add-to-calendar-button
DTSTAMP:20230214T091500Z
DTSTART;TZID=America/New_York:20230214T091500
DTEND;TZID=America/New_York:20230218T223000
SUMMARY:A sample event
DESCRIPTION:Just some descriptive text...
LOCATION:World Wide Web
STATUS:CONFIRMED
LAST-MODIFIED:20220830T192938Z
SEQUENCE:0
END:VEVENT
END:VCALENDAR

Get a specific offset

Use tzlib_get_offset(tzName, isoDate, isoTime) to get specific offset (relative to UTC), based on a provided date and time.
For example, you can provide tzName "Europe/Berlin", isoDate "2023-05-23", and isoTime "15:45" in order to retrieve the offset, which applies for this time zone at the 23rd of May in 2023 at exactly 15:45.

⚙️ Use it via API

Alternatively to the installation, you can make use of the public API.

Get time zones via API

Get them directly via https://tz.add-to-calendar-technology.com/api/zones.json.

Get the iCal time zone block via API

Once you have a valid zone name ready, you can get the ics part directly via the following URL scheme:

https://tz.add-to-calendar-technology.com/api/{zoneName}.ics

With {zoneName} being your time zone.

So, for New York, this would be https://tz.add-to-calendar-technology.com/api/America/New_York.ics.

This is case sensitive!

(Mind that this does not deliver a fully valid ics file, since it only contains the VTIMEZONE part.
You will need to combine this with your other event information.)

Background story

Time zones are a tricky thing. Especially because they do not follow any logical rules, but are rather randomly made up by politicians (and other people). This makes life hard for any software developer dealing with time.

Working on the Add to Calendar Button project, I was facing the same issue.
Generating iCal/ics files strictly requires time zone information - at least if you start dealing with recurring events. This time zone information needs to be more or less manually inserted. I started searching for some kind of official database or API.

There were a lot of libraries, which are quite big in terms of functionality and also size. Most of this is dangerous overhead, when you only need time zone information. No API, of course. Basically, nothing of any use to me.
The official database, on the other hand, is not directly accessible - especially not via JavaScript.

That's why I came up with this open source repository, pulling the latest official data, making it usable via JavaScript, and offering the most essential data, while stripping out all the rest - for best performance and bundle size.