Timezone Country #

Bidirectional mapping between IANA timezone identifiers and ISO 3166-1 country codes (alpha-2 and alpha-3).

Pure Dart. Zero dependencies. O(1) identifier lookups with compile-time const maps.

No platform channel, no plugin, no network call — a plain Dart library, so it behaves the same in a server, a CLI, a Flutter app and a release web build.

Features #

• Timezone → Country: Get the country code for any IANA timezone
• Country → Timezones: Get all timezones for a country
• Alpha-2 & Alpha-3: Full ISO 3166-1 support (US ↔ USA)
• Country-specific Zones: Europe/Oslo → 'NO', Europe/Copenhagen → 'DK'
• Legacy Resolution: Deprecated names are resolved on lookup (US/Eastern → 'US', Asia/Calcutta → 'IN')
• Multi-country Timezones: Europe/Brussels → ['BE', 'LU', 'NL']
• Country Names: 'JP' → 'Japan' (from Debian iso-codes)
• Flag Emoji: 'JP' → '🇯🇵' (pure Unicode arithmetic, zero data)
• Windows Timezones: 'Tokyo Standard Time' ↔ 'Asia/Tokyo' (from CLDR)
• Zone Display Names: 'America/Denver' → 'Mountain Standard Time' (from CLDR)
• Coordinates: 'Asia/Tokyo' → latitude and longitude, plus a nearest-city search
• String Extensions: Fluent API on String for quick conversions
• Validated Types: CountryCode and TimezoneId extension types — parse once, no null checks after
• Validation: Check if a timezone or country code is valid
• Enumeration: List all known timezones or country codes

Installation #

dependencies:
  timezone_country: ^1.2.0

dart pub add timezone_country
# or for Flutter projects:
flutter pub add timezone_country

Quick Start #

import 'package:timezone_country/timezone_country.dart';

// Timezone → Country
TimezoneConvert.timezoneToCountryCode('Asia/Tokyo');       // 'JP'
TimezoneConvert.timezoneToCountryCode('Asia/Tokyo',
    format: CountryCodeFormat.alpha3);                      // 'JPN'

// Country → Timezones
TimezoneConvert.countryToTimezones('US');                   // ['America/New_York', ...]
TimezoneConvert.countryToTimezones('USA');                  // same — auto-detects format

// Legacy resolution
TimezoneConvert.resolveTimezone('US/Eastern');              // 'America/New_York'

// Alpha-2 ↔ Alpha-3
TimezoneConvert.alpha2ToAlpha3('JP');                       // 'JPN'
TimezoneConvert.alpha3ToAlpha2('JPN');                      // 'JP'

// Country name & flag
TimezoneConvert.countryName('JP');                           // 'Japan'
TimezoneConvert.countryFlag('JP');                           // '🇯🇵'

// Windows timezones
TimezoneConvert.timezoneToWindows('Asia/Tokyo');            // 'Tokyo Standard Time'
TimezoneConvert.windowsToTimezone('Romance Standard Time'); // 'Europe/Paris'
TimezoneConvert.windowsToTimezone('Romance Standard Time',
    countryCode: 'BE');                                     // 'Europe/Brussels'

// Zone display names
TimezoneConvert.timezoneGenericName('America/Denver');      // 'Mountain Time'
TimezoneConvert.timezoneStandardName('America/Denver');     // 'Mountain Standard Time'
TimezoneConvert.timezoneDaylightName('America/Denver');     // 'Mountain Daylight Time'
TimezoneConvert.timezoneCity('Asia/Ho_Chi_Minh');           // 'Ho Chi Minh City'
TimezoneConvert.primaryTimezone('DE');                      // 'Europe/Berlin'

// Fixed-offset zones
TimezoneConvert.isKnownTimezone('Etc/UTC');                 // true
TimezoneConvert.timezoneFixedOffset('Etc/GMT-1');           // Duration(hours: 1)

// Location
TimezoneConvert.timezoneCoordinates('Asia/Tokyo');          // ≈ (35.65, 139.74)
TimezoneConvert.timezoneComment('America/New_York');        // IANA's description
TimezoneConvert.nearestTimezone(35.68, 139.76);             // 'Asia/Tokyo'

// String extensions
'Asia/Tokyo'.toCountryCode;                                 // 'JP'
'US'.toTimezones;                                           // ['America/New_York', ...]
'US/Eastern'.toCanonicalTimezone;                           // 'America/New_York'
'JP'.toCountryName;                                         // 'Japan'
'JP'.toFlag;                                                // '🇯🇵'

Validated types #

Validate a code once and the accessors stop returning null. Both are extension types over String — no wrapper object exists at runtime.

final country = CountryCode.tryParse('usa');  // null if not ISO 3166-1
country?.alpha2;     // 'US'
country?.alpha3;     // 'USA'
country?.name;       // 'United States'
country?.flag;       // '🇺🇸'
country?.timezones;  // [America/New_York, ...]

final zone = TimezoneId.tryParse('US/Eastern');  // null if not a known zone
zone?.id;              // 'America/New_York' — canonical
zone?.country.name;    // 'United States'
zone?.coordinates;     // ≈ (40.71, -74.01)
zone?.comment;         // IANA's description
zone?.windowsId;       // 'Eastern Standard Time'

Usage with Flutter #

This is a pure Dart package — it works in any Dart project including Flutter.

Dart's DateTime.now().timeZoneName returns abbreviations like 'EST' or 'CET', not IANA identifiers like 'America/New_York'. To get the IANA timezone ID from the device, use flutter_timezone:

dependencies:
  timezone_country: ^1.2.0
  flutter_timezone: ^5.1.0

import 'package:flutter_timezone/flutter_timezone.dart';
import 'package:timezone_country/timezone_country.dart';

// Get the device timezone and convert to country code
final timezone = await FlutterTimezone.getLocalTimezone(); // e.g. 'Asia/Tokyo'
final country = TimezoneConvert.timezoneToCountryCode(timezone); // 'JP'

// Or get the alpha-3 code directly
final country3 = TimezoneConvert.timezoneToCountryCode(
  timezone,
  format: CountryCodeFormat.alpha3,
); // 'JPN'

// Get all timezones available on the device
final available = await FlutterTimezone.getAvailableTimezones();
for (final tz in available) {
  print('$tz → ${TimezoneConvert.timezoneToCountryCode(tz)}');
}

On the web, without a plugin #

Browsers expose the IANA identifier through Intl, so no platform channel is involved and nothing has to be awaited:

import 'dart:js_interop';

@JS('Intl.DateTimeFormat')
extension type _DateTimeFormat._(JSObject _) implements JSObject {
  external factory _DateTimeFormat();
  external _ResolvedOptions resolvedOptions();
}

extension type _ResolvedOptions._(JSObject _) implements JSObject {
  external String get timeZone;
}

String? localCountryCode() =>
    TimezoneConvert.timezoneToCountryCode(_DateTimeFormat().resolvedOptions().timeZone);

Older browsers report a deprecated identifier here — Asia/Calcutta rather than Asia/Kolkata, Europe/Kiev rather than Europe/Kyiv. Both forms resolve, so no normalisation step is needed.

Bundle size #

Tree shaking works per data file: an app pays only for the maps it reaches. Measured with dart run tool/measure_size.dart, as the difference against an identical program that does not import the package.

Gzipped, which is what a browser downloads. Re-run the tool to check these against the current data rather than trusting the table.

API Reference #

TimezoneConvert #

String Extensions #

The String getters cover the country-code mappings only. Windows identifiers and coordinates are reachable through TimezoneConvert or the validated types.

CountryCode and TimezoneId #

Both are extension types over String: they cost nothing at runtime and print as the underlying code, but they are distinct static types. Pass .alpha2 or .id where a String is expected.

Raw Data Access #

For advanced use cases, raw const maps are available:

TimezoneConvert.timezoneToCountryMap;    // Map<String, String>
TimezoneConvert.timezoneToCountriesMap;  // Map<String, List<String>>
TimezoneConvert.countryToTimezonesMap;   // Map<String, List<String>>
TimezoneConvert.legacyTimezoneAliases;   // Map<String, String>
TimezoneConvert.alpha2ToAlpha3Map;       // Map<String, String>
TimezoneConvert.alpha3ToAlpha2Map;       // Map<String, String>
TimezoneConvert.countryNamesMap;         // Map<String, String>
TimezoneConvert.alpha2ToNumericMap;      // Map<String, String>
TimezoneConvert.numericToAlpha2Map;      // Map<String, String>
TimezoneConvert.timezoneCommentsMap;     // Map<String, String>
TimezoneConvert.timezoneCoordinatesMap;  // Map<String, (double, double)>
TimezoneConvert.timezoneToWindowsMap;    // Map<String, String>
TimezoneConvert.windowsToTimezoneMap;    // Map<String, Map<String, String>>

These maps and the lists returned by the API are unmodifiable. Mutating them throws UnsupportedError; copy first.

Data Sources #

• IANA Time Zone Database (zone1970.tab, zone.tab, backward) — timezone ↔ country mappings and legacy aliases. Check TimezoneConvert.ianaVersion for the exact version. Both zone tables are used: zone1970.tab supplies the multi-country lists, zone.tab supplies the country-specific zones that zone1970.tab merges away (Europe/Oslo, Europe/Copenhagen, and others). Column 2 of the zone tables supplies the coordinates, column 4 the English descriptions.
• ISO 3166-1 via Debian iso-codes — alpha-2 ↔ alpha-3 ↔ numeric country code mappings and English country names
• CLDR windowsZones.xml — Windows ↔ IANA timezone identifiers. Released on its own schedule, independent of the IANA version, and pinned to a release tag rather than the development branch. The mapping states the IANA release it was itself aligned to; read it from windowsZonesIanaVersion, and expect it to trail ianaVersion by years.
• CLDR metaZones.xml and common/main/en.xml — English zone display names, exemplar cities, and the primary zone of a country.
• CLDR common/bcp47/timezone.xml — which IANA zone each CLDR spelling stands for. backward may only link to a canonical zone, so it sends Atlantic/Jan_Mayen to Europe/Berlin and Pacific/Yap to Pacific/Port_Moresby; this table names the zone in the right country.
• IANA etcetera — the Etc/* fixed-offset zones. These carry no country, so they are reachable through isKnownTimezone and timezoneFixedOffset but stay out of allTimezones.

All data is embedded as compile-time const maps. No network requests, no file I/O, no runtime parsing.

Notes #

• Etc/* zones (Etc/UTC, Etc/GMT) have no country association in the IANA database. isValidTimezone('Etc/UTC') returns false and timezoneToCountryCode('Etc/UTC') returns null. Use isKnownTimezone to tell an unrecognised string apart from a real zone that simply has no country — devices do report these. timezoneFixedOffset gives the offset with its true sign, not the inverted one inside the identifier.
• The display names are English only, and every one of them is nullable. A zone with no current metazone has no generic, standard or daylight name; a zone that never leaves standard time has no daylight name. Nothing is synthesised to fill a gap, so a null means CLDR has no answer. Short abbreviations are deliberately not exposed: CLDR supplies them for only a handful of metazones in English, and they are ambiguous across regions.
• isValidCountryCode means "has at least one IANA timezone", which is narrower than ISO 3166-1 membership. Use isKnownCountryCode for the latter.
• nearestTimezone compares against the coordinates IANA gives each zone — the city the identifier is named after, not a polygon. It answers "which of these zones is closest", not "which zone contains this point", and the two disagree often — including inside a single country, so countryCode narrows the error without removing it. Treat the result as a guess.
• Some zones serve several countries because IANA merged them. Use timezoneToCountryCodes for the full list, and prefer the country-specific identifier (Europe/Oslo over Europe/Berlin) when you know the country.
• allTimezones lists one identifier per zone, with deprecated aliases and the Etc/* zones excluded. It matches the primary identifiers ECMA-402 defines, including keeping two zones apart where they serve different countries despite agreeing on the clock (Europe/Oslo and Europe/Berlin). Browsers expose the same set through Intl.supportedValuesOf('timeZone'), but engines are slow to follow IANA renames and still emit the superseded spelling, so the two lists disagree on the names even where they agree on the zones.

Non-goals #

This package maps identifiers. It does not do:

• Time arithmetic, UTC offsets or DST — use timezone. An embedded offset table would ship stale: offsets move with DST and on political notice. The Etc/* zones are the exception, being fixed by definition.
• Localized country names — English only. Use common_locale_data or country_codes.
• Dial codes — use country_codes.
• Timezone boundary lookup from a coordinate — that needs shapefiles. nearestTimezone is a nearest-city approximation, not a substitute.
• Wider country data (currencies, capitals, subdivisions) — use sealed_countries.
• Reading the device timezone — needs a platform channel. Use flutter_timezone and pass the result in, as shown above.

License #

MIT