iana-db-timezones

---

Automatically generated timezones from IANA DB tzdata-latest.tar.gz

• No external dependencies
• Weekly cron job to check for new iana timezone data
• Can be used both in both Node.js and Browser
• If you just need the json data - timezones.json

The fields for each timezone object are as follows:

Field Name	Description	Example Value
tzCode	The standard IANA Time Zone Database identifier (tz tzCode).	Kwajalein
label	A display string combining the tzCode and the current UTC offset.	Kwajalein (GMT+12:00)
utc	The current static UTC offset from UTC in +HH:MM or -HH:MM format. Reflects current DST.	+12:00
locationLabel	A human-readable name for the primary city or location associated with the timezone.	Kwajalein
countryCodes	An array of ISO 3166-1 alpha-2 country codes associated with this timezone.	['KI', ...]
geographicArea	The continent or ocean region the timezone is located in.	Pacific
type	Indicates if the entry is a Canonical timezone or a Link (an alias) to another timezone.	Canonical or Link
parent	(Present for Link types) The tzCode of the canonical timezone that this link points to.	Europe/London
comments	(Optional) Additional notes from the IANA database.	'Mountain (most areas)'
children	(Present for Canonical types) An array of tzCode values for the zones that are links pointing to this.	['EST5EDT', ...]
location	The raw location name used in the IANA database (e.g., the last part of the tzCode before underscores).	Kwajalein

Inspired by: list of tz database in wikipedia

• IANA DB Version: 2025b
• Updated: Thu, 15 May 2025 06:19:36 GMT
• Last Modified: Sat, 22 Mar 2025 21:45:31 GMT
• Number of zones: 597
• Zones: TIMEZONES.md
• Tests Coverage: coverage
• Files used from IANA DB: zone.tab, zone1970.tab, etcetera, backward

---

Overview

iana-db-timezones provides up-to-date information about timezones based on the IANA Time Zone Database. Unlike some other packages, this package provides richer details about each timezone, including its type (Canonical or Link), children/parent, current UTC offset, associated country codes, geographic area, location, and label.

Whenever new data is available, a new version of this package is automatically generated, tested, and published to npm. This ensures you always have the latest timezone information. The library is using semantic versioning.

The package supports CommonJS (CJS), ES Modules (ESM), and includes full TypeScript definitions.

Installation

You can install the package using npm or yarn:

npm install iana-db-timezones

or

yarn add iana-db-timezones

or

pnpm add iana-db-timezones

Usage

The package exports several utilities and the raw timezone data.

Importing the package

ES Modules (ESM):

import tzdb, { TimezoneCode, Timezone } from 'iana-db-timezones';

CommonJS (CJS):

const tzdb = require('iana-db-timezones');

Accessing the raw data

The raw timezone data is available as an object and an ES6 Map.

Raw Data Object (zones):

import tzdb from 'iana-db-timezones';

const allZones = tzdb.zones;
console.log(allZones['Europe/Sofia']);
/*
// => {
//   tzCode: 'Europe/Sofia',
//   type: 'Canonical',
//   label: 'Europe/Sofia (GMT+03:00)',
//   countryCodes: [ 'BG' ],
//   location: 'Sofia',
//   locationLabel: 'Sofia',
//   geographicArea: 'Europe',
//   utc: '+03:00'
// }
*/

ES6 Map (map):

The data is also available as an ES6 Map for potentially better performance when looking up zones by tzCode.

import tzdb from 'iana-db-timezones';

const zoneMap = tzdb.map;
console.log(zoneMap.get('America/New_York'));
/*
// => {
//   children: [ 'EST5EDT', 'US/Eastern' ],
//   comments: 'Eastern (most areas)',
//   countryCodes: [ 'US' ],
//   geographicArea: 'America',
//   label: 'America/New_York (GMT-04:00)',
//   location: 'New_York',
//   locationLabel: 'New York',
//   tzCode: 'America/New_York',
//   type: 'Canonical',
//   utc: '-04:00'
// }
*/

Utility Functions

The package provides helper functions for common tasks.

getZone(zoneName: TimezoneCode): Timezone | null

Returns the timezone object for a given tzCode, or null if not found.

import { getZone } from 'iana-db-timezones';

const sofiaZone = getZone('Europe/Sofia');
console.log(sofiaZone);
// => { ... detailed zone object ... }

const unknownZone = getZone('Invalid/Timezone');
console.log(unknownZone);
// => null

getZoneUTC(zoneName: TimezoneCode): string | null

Returns the current UTC offset for a timezone in +HH:MM or -HH:MM format, or null if the zone or offset is not available.

import { getZoneUTC } from 'iana-db-timezones';

console.log(getZoneUTC('Europe/Sofia'));
// => '+03:00'

console.log(getZoneUTC('America/New_York'));
// => '-04:00' // Note: This reflects the *current* offset, including DST if applicable.

console.log(getZoneUTC('Invalid/Timezone'));
// => null

getZoneISODate(zoneName: TimezoneCode): string | null

Returns the current ISO 8601 date-time string adjusted to the timezone's current offset, or null if the zone or offset is not available or invalid. The format is YYYY-MM-DDTHH:mm:ss.sss+HH:MM or YYYY-MM-DDTHH:mm:ss.sss-HH:MM.

import { getZoneISODate } from 'iana-db-timezones';

console.log(getZoneISODate('Europe/Sofia'));
// => '2025-05-12T08:25:49.322+03:00'

console.log(getZoneISODate('Invalid/Timezone'));
// => null

TypeScript Support

The package is written in TypeScript and includes full type definitions. You can import the types directly:

import type { CanonicalTimezone, LinkTimezone, Timezone, TimezoneCode } from 'iana-db-timezones';

const zone: Timezone | null = ianatz.getZone('Europe/London');

// Narrow the zone and typescript intellisense will help you
if (zone && zone.type === 'Canonical') {
  console.log(zone.children);
}

---

Full Timezone List

A comprehensive list of all supported timezones, grouped by geographic area, can be found in TIMEZONES.md.