- Notifications
You must be signed in to change notification settings - Fork56
🕰 Simplified, grouped and always up to date list of time zones, with major cities
License
vvo/tzdb
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This is a list and npm package of:
- "simplified"IANA time zones with their alternative names like
Pacific 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 names for compatibility
The data and npm packages areautomatically updated whenever there are changes tohttps://www.geonames.org/ which is generated from IANA databases.
This is useful whenever you want to build a time zone select menu in your application.
Installation:
npm add @vvo/tzdb
Usage:
import{getTimeZones,rawTimeZones,timeZonesNames,abbreviations}from"@vvo/tzdb";
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 runtimecurrentTimeFormat:"-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"}
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",},// ...];
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",// ...];
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 byrawTimeZones orgetTimeZones().
- 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 the
nameattribute (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:
- make sure to save the
constvalue=timeZones.find((timeZone)=>{returndbData.timeZone===timeZone.name||timeZone.group.includes(dbData.timeZone);});
About
🕰 Simplified, grouped and always up to date list of time zones, with major cities