Cldr.DateTime.Timezone (Cldr Dates & Times v2.23.0)

Functions to format IANA time zone IDs, including the time zone field of a DateTime.t/0.

Time Zone Names

There are three main types of formats for zone identifiers: GMT, generic (wall time), and standard/daylight.

Standard and daylight are equivalent to a particular offset from GMT, and can be represented by a GMT offset as a fallback. In general, this is not true for the generic format, which is used for picking timezones or for conveying a timezone for specifying a recurring time (such as a meeting in a calendar). For either purpose, a GMT offset would lose information.

Supported Time Zone IDs

NATO time zone names are not supported, only IANA time zone IDs.

Time Zone Format Terminology

The following terminology defines more precisely the formats that are used.

Generic non-location format

Reflects "wall time" (what is on a clock on the wall): used or recurring events, meetings, or anywhere people do not want to be overly specific. For example, "10 am Pacific Time" will be GMT-8 in the winter, and GMT-7 in the summer.

"Pacific Time" (long)
"PT" (short)

This format is returned from Cldr.DateTime.Time.non_location_format/2 with type: :generic which is the default.

Generic partial location format

Reflects "wall time": used as a fallback format when the generic non-location format is not specific enough. For example:

"Pacific Time (Canada)" (long)
"PT (Whitehorse)" (short)

Generic location format

Reflects "wall time": a primary function of this format type is to represent a time zone in a list or menu for user selection of time zone. It is also a fallback format when there is no translation for the generic non-location format. Times could also be organized hierarchically by country for easier lookup.

France Time
Italy Time
Japan Time
United States
Chicago Time
Denver Time
Los Angeles Time
New York Time
United Kingdom Time

Note: A generic location format is constructed by a part of time zone ID representing an exemplar city name or its country as the final fallback. However, there are Unicode time zones which are not associated with any locations, such as "Etc/GMT+5" and "PST8PDT".

Although the date format pattern "VVVV" specifies the generic location format, but it displays localized GMT format for these. Some of these time zones observe daylight saving time, so the result (localized GMT format) may change depending on input date. For generating a list for user selection of time zone with format "VVVV", these non-location zones should be excluded.

This format is returned from Cldr.DateTime.Time.location_format/2 with type: :generic which is the default.

Specific non-location format

Reflects a specific standard or daylight time, which may or may not be the wall time. For example, "10 am Pacific Standard Time" will be GMT-8 in the winter and GMT-7 in the summer.

"Pacific Standard Time" (long)
"PST" (short)
"Pacific Daylight Time" (long)
"PDT" (short)

This format is returned from Cldr.DateTime.Time.non_location_format/2 with type: :standard or type :daylight.

Specific location format

This format does not have a symbol, but is used in the fallback chain for the specific non-location format. Like the generic location format it uses time zone locations, but formats these in a zone-variant aware way, e.g. "France Summer Time".

This format is returned from Cldr.DateTime.Time.location_format/2 with type: :standard or type :daylight.

Localized GMT format

A constant, specific offset from GMT (or UTC), which may be in a translated form. There are two styles for this.

The long format always uses 2-digit hours field and minutes field, with optional 2-digit seconds field. The short format is intended for the shortest representation and uses hour fields without leading zero, with optional 2-digit minutes and seconds fields.

The digits used for hours, minutes and seconds fields in this format are the locale's default decimal digits:

"GMT+03:30" (long)
"GMT+3:30" (short)
"UTC-03.00" (long)
"UTC-3" (short)
"Гринуич+03:30" (long)

Otherwise (when the offset from GMT is zero, referring to GMT itself) the style specified by the following format is used:

"GMT"
"UTC"
"Гринуич"

ISO 8601 time zone formats

The formats based on the [ISO 8601] local time difference from UTC ("+" sign is used when local time offset is 0), or the UTC indicator ("Z" - only when the local time offset is 0 and the specifier X* is used). The ISO 8601 basic format does not use a separator character between hours and minutes field, while the extended format uses colon (':') as the separator.

The ISO 8601 basic format with hours and minutes fields is equivalent to RFC 822 zone format.

"-0800" (basic)
"-08" (basic - short)
"-08:00" (extended)
"Z" (UTC)

Note: This specification extends the original ISO 8601 formats and some format specifiers append seconds field when necessary.

Examples for fomat differences

The following shows representative examples of the different formats:

  iex> {:ok, date_time} = DateTime.new(~D[2025-07-01], ~T[00:00:00], "Australia/Sydney")
  iex> Cldr.DateTime.Timezone.non_location_format(date_time, type: :daylight)
  {:ok, "Australian Eastern Daylight Time"}
  iex> Cldr.DateTime.Timezone.non_location_format(date_time, type: :specific)
  {:ok, "Australian Eastern Standard Time"}
  iex> Cldr.DateTime.Timezone.non_location_format(date_time, type: :generic)
  {:ok, "Australian Eastern Time"}
  iex> Cldr.DateTime.Timezone.location_format(date_time, type: :daylight)
  {:ok, "Sydney Daylight Time"}
  iex> Cldr.DateTime.Timezone.location_format(date_time, type: :specific)
  {:ok, "Sydney Standard Time"}
  iex> Cldr.DateTime.Timezone.location_format(date_time, type: :generic)
  {:ok, "Sydney Time"}
  iex> Cldr.DateTime.Timezone.gmt_format(date_time)
  {:ok, "GMT+10:00"}
  iex> Cldr.DateTime.Timezone.iso_format(date_time)
  {:ok, "+1000"}

GMT and UTC time zone formats

Some valid time zones are not associated with a city of territory (country). Therefore they return an error for the location formats. The can producxe a valid result for the non-location format and the GMT format.

Non-location format

  iex> Cldr.DateTime.Timezone.non_location_format("GMT")
  {:ok, "Greenwich Mean Time"}

  iex> Cldr.DateTime.Timezone.non_location_format("UTC")
  {:ok, "Coordinated Universal Time"}

Location format

  iex> Cldr.DateTime.Timezone.location_format("GMT")
  {:error,
   {Cldr.DateTime.NoTerritoryForTimezone,
    "No territory was found for time zone \"Etc/GMT\""}}

  iex> Cldr.DateTime.Timezone.location_format("UTC")
  {:error,
   {Cldr.DateTime.NoTerritoryForTimezone,
    "No territory was found for time zone \"Etc/UTC\""}}

GMT format

  iex> Cldr.DateTime.Timezone.gmt_format("Australia/Adelaide")
  {:ok, "GMT+09:30"}

  iex> Cldr.DateTime.Timezone.gmt_format("UTC")
  {:ok, "GMT"}

  iex> Cldr.DateTime.Timezone.gmt_format("GMT")
  {:ok, "GMT"}

Summary

Functions

canonical_time_zone(time_zone)

Returns the canonical time zone name for a given time zone identifier.

canonical_time_zones()

Returns the canonical time zone mapping.

exemplar_city(date_time_or_zone, options \\ [])

Return the localized exemplar City for a time zone.

gmt_format(date_time_or_zone, options \\ [])

Return the localized GMT time zone format for a time zone ID or a DateTime.t/0.

iso_format(date_time_or_zone, options \\ [])

Return the localized ISO 8601 time zone format for a time zone ID or a DateTime.t/0.

iso_format_type(time, arg2, arg3, z_for_zero)

location_format(date_time_or_zone, options \\ [])

Return the localized location time zone format for a time zone ID or a DateTime.t/0.

meta_zone_ids()

Returns the mapping of time zone short IDs to metazone data.

meta_zone_mapping()

Returns the mapping of a metazone to a time zone long ID.

meta_zones()

Returns the metazone data.

no_exemplar_city_error(time_zone)

non_location_format(date_time_or_zone, options \\ [])

Return the localized non-location time zone format for a time zone ID or a DateTime.t/0.

preferred_zone_for_locale(time_zone, options \\ [])

Returns the preferred time zone name for a given time zone and locale.

primary_zones()

Returns the primary time zone for certain territories.

time_from_zone_offset(time)

Converts the time zone offset of a Time or DateTime into seconds.

Functions

canonical_time_zone(time_zone)

(since 2.23.0)

Returns the canonical time zone name for a given time zone identifier.

canonical_time_zones()

(since 2.23.0)

Returns the canonical time zone mapping.

exemplar_city(date_time_or_zone, options \\ [])

(since 2.23.0)

@spec exemplar_city(
  date_time_or_zone :: String.t() | DateTime.t(),
  options :: Keyword.t()
) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Return the localized exemplar City for a time zone.

The examplar city is, by default, the last segment of a time zone ID. For some time zones there is an explicit localized exemplar which, if it exists, is returned instead.

Arguments

date_time_or_zone is any time zone ID or any DateTime.t/0.
options is a keyword list of options.

Options

:locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0.
:backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

Returns

{:ok, exemplar_city} or
{:error, {exception, reason}}.

Examples

  iex> Cldr.DateTime.Timezone.exemplar_city("Australia/Sydney")
  {:ok, "Sydney"}

  iex> Cldr.DateTime.Timezone.exemplar_city("Europe/Kiev")
  {:ok, "Kyiv"}

  iex> Cldr.DateTime.Timezone.exemplar_city("America/Indiana/Knox")
  {:ok, "Knox, Indiana"}

  iex> Cldr.DateTime.Timezone.exemplar_city("Europe/Kiev", locale: :ja)
  {:ok, "キーウ"}

  iex> Cldr.DateTime.Timezone.exemplar_city("Etc/Unknown")
  {:ok, "Unknown City"}

  iex> Cldr.DateTime.Timezone.exemplar_city("Etc/UTC")
  {:error, {Cldr.DateTime.UnknownExemplarCity, "No exemplar city is known for \"Etc/UTC\""}}

  iex> Cldr.DateTime.Timezone.exemplar_city("Etc/GMT+5")
  {:error, {Cldr.DateTime.UnknownExemplarCity, "No exemplar city is known for \"Etc/GMT+5\""}}

  iex> Cldr.DateTime.Timezone.exemplar_city("Europe/Frankenstein")
  {:error,
   {Cldr.UnknownTimezoneError, "Unknown time zone \"Europe/Frankenstein\""}}

gmt_format(date_time_or_zone, options \\ [])

(since 2.23.0)

@spec gmt_format(
  date_time_or_zone :: String.t() | DateTime.t(),
  options :: Keyword.t() | map()
) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Return the localized GMT time zone format for a time zone ID or a DateTime.t/0.

Time zones other than UTC

When date_time_or_zone is a string and it is not UTC or GMT, a Time Zone database must be configured or provided as the option :time_zone_database.

Arguments

date_time_or_zone is any time zone ID or any DateTime.t/0.
options is a keyword list of options.

Options

:locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0.
:backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.
:time_zone_database determines the time zone database to use when shifting time zones. Shifting time zones only occurs if the date_time_or_zone is set to a string time zone ID. The default is Calendar.get_time_zone_database/0.

Returns

{:ok, gmt_format} or
{:error, {exception, reason}}.

Notes

The digits of the GMT format are presented in the default number system of the locale defined in the locale option.

Examples

iex> Cldr.DateTime.Timezone.gmt_format(DateTime.utc_now())
{:ok, "GMT"}

iex> {:ok, standard_time} = DateTime.new(~D[2025-06-01], ~T[00:00:00], "Australia/Sydney")
iex> Cldr.DateTime.Timezone.gmt_format(standard_time)
{:ok, "GMT+10:00"}

iex> {:ok, summer_time} = DateTime.new(~D[2025-01-01], ~T[00:00:00], "Australia/Sydney")
iex> Cldr.DateTime.Timezone.gmt_format(summer_time)
{:ok, "GMT+11:00"}
iex> Cldr.DateTime.Timezone.gmt_format(summer_time, locale: :fr)
{:ok, "UTC+11:00"}

iex> Cldr.DateTime.Timezone.gmt_format "Canada/Newfoundland", locale: :ar
{:ok, "غرينتش-02:30"}

iex> {:ok, summer_time} = DateTime.new(~D[2025-06-01], ~T[00:00:00], "America/Los_Angeles")
iex> Cldr.DateTime.Timezone.gmt_format(summer_time)
{:ok, "GMT-07:00"}

iex> {:ok, gmt} = DateTime.new(~D[2025-06-01], ~T[00:00:00], "GMT")
iex> Cldr.DateTime.Timezone.gmt_format(gmt)
{:ok, "GMT"}

iso_format(date_time_or_zone, options \\ [])

(since 2.23.0)

@spec iso_format(
  date_time_or_zone :: String.t() | DateTime.t(),
  options :: Keyword.t() | map()
) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Return the localized ISO 8601 time zone format for a time zone ID or a DateTime.t/0.

Time zones other than UTC

When date_time_or_zone is a string and it is not UTC or GMT, a Time Zone database must be configured or provided as the option :time_zone_database.

Arguments

date_time_or_zone is any time zone ID or any DateTime.t/0.
options is a keyword list of options.

Options

:format is either :long (the default) or :short.
- :short will always render the hour offset and only render the minute offset if it is not zero.
- :long will always render the hour and minute offsets.
- :full will always render the hour and minute offsets and only render the second offset if it is not zero. This is an extension to the ISO 8601 standard.
:type is either :basic (the default), or :extended.
- :basic renders the time zone hour, optional minute and optional second with no spacing or separator between then.
- :extended renders the time zone hour, optional minute and optional second with a : separator between them.
:z_for_zero is a truthy or falsy value to indicate whether or not to use the Z indicator when the time zone offset is zero. The default is true.
:time_zone_database determines the time zone database to use when shifting time zones. Shifting time zones only occurs if the date_time_or_zone is set to a string time zone ID. The default is Calendar.get_time_zone_database/0.

Returns

{:ok, iso_format} or
{:error, {exception, reason}}

Examples

iex> Cldr.DateTime.Timezone.iso_format(DateTime.utc_now())
{:ok, "Z"}
iex> Cldr.DateTime.Timezone.iso_format(DateTime.utc_now(), z_for_zero: false)
{:ok, "+0000"}
iex> Cldr.DateTime.Timezone.iso_format(DateTime.utc_now(), z_for_zero: false, type: :extended)
{:ok, "+00:00"}

iex> {:ok, standard_time} = DateTime.new(~D[2025-06-01], ~T[00:00:00], "Australia/Sydney")
iex> Cldr.DateTime.Timezone.iso_format(standard_time)
{:ok, "+1000"}
iex> Cldr.DateTime.Timezone.iso_format(standard_time, format: :short)
{:ok, "+10"}
iex> Cldr.DateTime.Timezone.iso_format(standard_time, format: :long)
{:ok, "+1000"}

iex> {:ok, standard_time} = DateTime.new(~D[2025-06-01], ~T[00:00:00], "Australia/Adelaide")
iex> Cldr.DateTime.Timezone.iso_format(standard_time, format: :short)
{:ok, "+0930"}
iex> Cldr.DateTime.Timezone.iso_format(standard_time, format: :long)
{:ok, "+0930"}
iex> Cldr.DateTime.Timezone.iso_format(standard_time, format: :long, type: :extended)
{:ok, "+09:30"}

iso_format_type(time, arg2, arg3, z_for_zero)

location_format(date_time_or_zone, options \\ [])

(since 2.23.0)

@spec location_format(
  date_time_or_zone :: String.t() | DateTime.t(),
  options :: Keyword.t() | map()
) :: {:ok, String.t()} | {:error, {module(), String.t()}}

Return the localized location time zone format for a time zone ID or a DateTime.t/0.

Arguments

date_time_or_zone is any time zone ID or any DateTime.t/0.
options is a keyword list of options.

Options

:locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0.
:backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.
:date_time is the date_time to be used to ascertain if the standard or daylight time zone information is required. The default is DateTime.utc_now/0.
:type is either :generic (the default), :specific, :standard or:daylight. :specific indicates that :standard or :daylight will be selected based upon the time zone of the :date_time option.

Returns

{:ok, non_location_format} or
{:error, {exception, reason}}.

Examples

iex> Cldr.DateTime.Timezone.location_format("Australia/Sydney")
{:ok, "Sydney Time"}

iex> Cldr.DateTime.Timezone.location_format("Australia/Sydney", type: :daylight)
{:ok, "Sydney Daylight Time"}

# Only one time zone in Italy so we use the territory name
iex> Cldr.DateTime.Timezone.location_format "Europe/Rome", type: :daylight
{:ok, "Italy Daylight Time"}

iex> Cldr.DateTime.Timezone.location_format("Asia/Shanghai")
{:ok, "China Time"}

iex> Cldr.DateTime.Timezone.location_format("America/Phoenix")
{:ok, "Phoenix Time"}

iex> Cldr.DateTime.Timezone.location_format("Australia/Sydney", locale: :fr)
{:ok, "heure : Sydney"}

iex> Cldr.DateTime.Timezone.location_format("Europe/Rome", locale: :ja)
{:ok, "イタリア時間"}

iex> Cldr.DateTime.Timezone.location_format("America/New_York", locale: :fr, type: :daylight)
{:ok, "New York (heure d’été)"}

iex> Cldr.DateTime.Timezone.location_format("America/New_York", locale: :fr, type: :standard)
{:ok, "New York (heure standard)"}

meta_zone_ids()

(since 2.23.0)

Returns the mapping of time zone short IDs to metazone data.

meta_zone_mapping()

(since 2.23.0)

Returns the mapping of a metazone to a time zone long ID.

meta_zones()

(since 2.23.0)

Returns the metazone data.

no_exemplar_city_error(time_zone)

non_location_format(date_time_or_zone, options \\ [])

(since 2.23.0)

@spec non_location_format(
  date_time_or_zone :: String.t() | DateTime.t(),
  options :: Keyword.t()
) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Return the localized non-location time zone format for a time zone ID or a DateTime.t/0.

Arguments

date_time_or_zone is any time zone ID or any DateTime.t/0.
options is a keyword list of options.

Options

:locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0.
:backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.
:date_time is the date_time to be used to ascertain if the standard or daylight time zone information is required. The default is DateTime.utc_now/0.
:format is either :long (the default) or :short.
:type is either :generic (the default), :specific, :standard or:daylight. :specific indicates that :standard or :daylight will be selected based upon the time zone of the :date_time option.

Returns

{:ok, non_location_format} or
{:error, {exception, reason}}.

Examples

iex> Cldr.DateTime.Timezone.non_location_format("Australia/Sydney")
{:ok, "Australian Eastern Time"}

iex> Cldr.DateTime.Timezone.non_location_format("Australia/Sydney", type: :daylight)
{:ok, "Australian Eastern Daylight Time"}

iex> Cldr.DateTime.Timezone.non_location_format("Asia/Shanghai")
{:ok, "China Time"}

iex> Cldr.DateTime.Timezone.non_location_format("Australia/Sydney", locale: :fr)
{:ok, "heure de l’Est de l’Australie"}

iex> Cldr.DateTime.Timezone.non_location_format("America/Phoenix")
{:ok, "Mountain Time (Phoenix)"}

iex> Cldr.DateTime.Timezone.non_location_format("America/Phoenix", format: :short)
{:ok, "MT (Phoenix)"}

iex> Cldr.DateTime.Timezone.non_location_format("Europe/Dublin")
{:ok, "Greenwich Mean Time (Ireland)"}

iex> Cldr.DateTime.Timezone.non_location_format("Europe/Rome", locale: :ja)
{:ok, "中央ヨーロッパ時間（イタリア）"}

preferred_zone_for_locale(time_zone, options \\ [])

(since 2.23.0)

Returns the preferred time zone name for a given time zone and locale.

Arguments

time_zone is any valid IANA time zone name.
options is a keyword list of options.

Options

:locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0.
:backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.
:date_time is the date_time to be used to ascertain the correct time zone information applicable for this date time. The default is DateTime.utc_now/0.

Returns

{:ok, preferred_time_zone_name}
{:error, {exception, reason}}

Examples

iex> Cldr.DateTime.Timezone.preferred_zone_for_locale("America/New_York", locale: "en")
{:ok, "America/New_York"}

iex> Cldr.DateTime.Timezone.preferred_zone_for_locale("America/New_York", locale: "en-CA")
{:ok, "America/Toronto"}

iex> Cldr.DateTime.Timezone.preferred_zone_for_locale("PST8PDT", locale: "en")
{:ok, "America/Los_Angeles"}

iex> Cldr.DateTime.Timezone.preferred_zone_for_locale("PST8PDT", locale: "en-CA")
{:ok, "America/Vancouver"}

iex> Cldr.DateTime.Timezone.preferred_zone_for_locale "America/Los_Angeles", locale: "ja"
{:ok, "America/Los_Angeles"}

primary_zones()

(since 2.23.0)

Returns the primary time zone for certain territories.

time_from_zone_offset(time)

Converts the time zone offset of a Time or DateTime into seconds.