IANA timezone identifiers, versioned offset observations, and instant-aware offset lookup.

Country records contain timezone entries whose authoritative field is the IANA zoneName. The dataset currently contains 428 country-timezone records; a zone can appear under more than one country.

import { CountryStateCity } from '@tansuasici/country-state-city';

const zones = CountryStateCity.getAllTimezones();
const winter = CountryStateCity.getTimezoneOffset(
  'America/New_York',
  '2026-01-15T12:00:00Z'
);
const summer = CountryStateCity.getTimezoneOffset(
  'America/New_York',
  '2026-07-15T12:00:00Z'
);

getAllTimezones() returns sorted, unique IANA identifiers. getTimezoneOffset() accepts a Date, ISO string, or epoch number and returns:

{
  gmtOffset: number;      // seconds from UTC
  gmtOffsetName: string;  // UTC±HH:MM
  observedAt: string;     // normalized ISO instant
}

The gmtOffset and gmtOffsetName stored on country records are observations at 2026-01-15T00:00:00.000Z; they are not permanent current-time values. Use getTimezoneOffset(zoneName, at) for daylight-saving-aware calculations at a requested instant.

Legacy abbreviation and tzName fields are descriptive, not authoritative. Store the IANA zoneName when persisting timezone choices.