timezone-country

Map IANA timezone identifiers to ISO 3166-1 alpha-2 country codes. 420 timezones covered. Zero dependencies.

Install

npm install timezone-country

Usage

import { getCountryCode, getTimezones, isValidTimezone, timezonesToCountry } from 'timezone-country'

// Detect the current user's country from their browser/runtime timezone
getCountryCode()              // "br" (depends on local timezone)

// List all timezones for a country
getTimezones('BR')            // ["America/Araguaina", "America/Bahia", "America/Sao_Paulo", ...]
getTimezones('JP')            // ["Asia/Tokyo"]
getTimezones('br')            // same — input is case-insensitive

// Check if a timezone string is valid
isValidTimezone('Asia/Tokyo') // true
isValidTimezone('Fake/Zone')  // false

// Access the raw map directly
timezonesToCountry['Europe/London'] // "gb"

API

getCountryCode(): string | undefined

Returns the ISO 3166-1 alpha-2 country code (lowercase) for the current runtime's timezone, detected via Intl.DateTimeFormat().resolvedOptions().timeZone. Returns undefined if the timezone is not in the dataset (e.g. UTC).

getTimezones(countryCode: string): string[]

Returns all IANA timezone identifiers for the given country code. Input is case-insensitive. Returns [] for unknown country codes.

isValidTimezone(timezone: string): boolean

Returns true if the string is a recognized IANA timezone in the dataset. Case-sensitive (IANA timezone names are case-sensitive).

timezonesToCountry: Record<string, string>

The raw 420-entry map from IANA timezone identifier to lowercase ISO 3166-1 alpha-2 country code. Exported for custom lookups.

Browser (script tag)

<script src="https://unpkg.com/timezone-country/dist/index.iife.js"></script>
<script>
  console.log(TimezoneCountry.getCountryCode())
  console.log(TimezoneCountry.getTimezones('US'))
</script>

TypeScript

Full type declarations are included. No @types package needed.

import type { } from 'timezone-country' // types are auto-imported

Development

npm test          # run tests (vitest)
npm run build     # build dist/ (tsup)