tzdb

This is a list and npm package of:

• "simplified"IANA time zoneswith their alternative names likePacific Timeinstead ofAmerica/Los_Angeles,along with major cities for each time zone.
• all existing raw IANA time zones names
• "raw" offsets along with current time offsets
• also includesdeprecated time zone namesfor compatibility

The data and npm packages areautomatically updatedwhenever there are changes tohttps:// geonames.org/which is generated from IANA databases.

This is useful whenever you want to build a time zone select menu in your application.

NPM package

Installation:

npm add @vvo/tzdb

Usage:

import{getTimeZones,rawTimeZones,timeZonesNames,abbreviations}from"@vvo/tzdb";

API

getTimeZones()

consttimeZones=getTimeZones();

// You can also provide an optional parameter to include UTC in the result.
// This adds a time zone with the name "UTC" and a fixed offset of 0.
consttimeZonesWithUtc=getTimeZones({includeUtc:true});

This method returns an array of time zones objects:

[
//...
{
name:"America/Los_Angeles",
alternativeName:"Pacific Time",
group:["America/Los_Angeles"],
continentCode:"NA",
continentName:"North America",
countryName:"United States",
countryCode:"US",
mainCities:["Los Angeles","San Diego","San Jose","San Francisco"],
rawOffsetInMinutes:-480,
abbreviation:"PST",
rawFormat:"-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
currentTimeOffsetInMinutes:-420,// "current" time zone offset, this is why getTimeZones() is a method and not just an object: it works at runtime
currentTimeFormat:"-07:00 Pacific Time - Los Angeles, San Diego",
},
//...
];

When relevant, time zones are grouped. The rules for grouping are:

• if the time zones are in the same country
• if the DST or summer time offsets are the same
• if the non-DST, non-summer time offsets are the same
• then we group the time zones
• the "main" time zone name (nameattribute), is always the one from the most populated city

Here's a grouping example:

{
name:"America/Dawson_Creek",
alternativeName:"Mountain Time",
group:["America/Creston","America/Dawson_Creek","America/Fort_Nelson"],
continentCode:"NA",
continentName:"North America",
countryName:"Canada",
countryCode:"CA",
mainCities:["Fort St. John","Creston","Fort Nelson"],
rawOffsetInMinutes:-420,
abbreviation:"MST",
rawFormat:"-07:00 Mountain Time - Fort St. John, Creston, Fort Nelson",
currentTimeOffsetInMinutes:-420,
currentTimeFormat:"-07:00 Mountain Time - Fort St. John, Creston"
}

rawTimeZones

This is an array of time zone objects without the current time information:

[
//...
{
name:"America/Los_Angeles",
alternativeName:"Pacific Time",
group:["America/Los_Angeles"],
continentCode:"NA",
continentName:"North America",
countryName:"United States",
countryCode:"US",
mainCities:["Los Angeles","San Diego","San Jose","San Francisco"],
rawOffsetInMinutes:-480,
abbreviation:"PST",
rawFormat:"-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
},
//...
];

timeZonesNames

This is an array of time zone names:

[
//...
"America/Juneau",
"America/Kentucky/Louisville",
"America/Kentucky/Monticello",
"America/Kralendijk",
"America/La_Paz",
"America/Lima",
"America/Los_Angeles",
"America/Lower_Princes",
"America/Maceio",
"America/Managua",
"America/Manaus",
"America/Marigot",
"America/Martinique",
"America/Matamoros",
//...
];

abbreviations

This is an object mapping timezone abbreviations to their full forms:

{
//...
"Australian Central Daylight Time":"ACDT",
"Australian Central Standard Time":"ACST",
"Australian Central Time":"ACT",
"Australian Central Western Standard Time":"ACWST",
"Australian Eastern Daylight Time":"AEDT",
"Australian Eastern Standard Time":"AEST",
"Australian Eastern Time":"AET",
"Australian Western Daylight Time":"AWDT",
"Australian Western Standard Time":"AWST",
"Azerbaijan Summer Time":"AZST",
"Azerbaijan Time":"AZT",
"Azores Summer Time":"AZOST",
"Azores Time":"AZOT",
"Bangladesh Standard Time":"BST",
"Bhutan Time":"BTT",
"Bolivia Time":"BOT",
//...
};

Caution:Although abbreviations can be easy to lookup, they can be misleading. For example: CST can refer to Central Standard Time (-06.00 UTC), China Standard Time (+06.00 UTC) or Cuba Standard Time (-05.00 UTC). And abbreviation full forms don't directly map to any property in the time zone objects returned byrawTimeZonesorgetTimeZones().

Notes

• We provide two cities when grouping happens, ranked by population
• We provide alternative names ( "Pacific Time" for "America/Los_Angeles" ) and remove "Standard", "Daylight" or "Summer" from them
• If you're using this to build a time zone selector and saving to a database then:
  • make sure to save thenameattribute (America/Los_Angeles) in your database
  • when displaying the select with a default value from your database, either select the time zone name that matches, or if the time zone name is part of the group. Example:

constvalue=timeZones.find((timeZone)=>{
returndbData.timeZone===timeZone.name||timeZone.group.includes(dbData.timeZone);
});