# `Cldr.DateTime.Timezone`
[🔗](https://github.com/elixir-cldr/cldr_dates_times/blob/v2.25.6/lib/cldr/format/date_time_timezone.ex#L1)

Functions to format [IANA time zone IDs](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones),
including the time zone field of a `t: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  {: .info}
>
> [NATO time zone names](https://en.wikipedia.org/wiki/Military_time_zone) are not supported, only
> [IANA time zone IDs](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

### 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> {:ok, gmt_format} = Cldr.DateTime.Timezone.gmt_format("Australia/Adelaide")
      iex> gmt_format in ["GMT+09:30", "GMT+10:30"]
      true

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

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

# `canonical_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`
*since 2.23.0* 

```elixir
@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
  `t: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 `t: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 Location"}

      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`
*since 2.23.0* 

```elixir
@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 `t:DateTime.t/0`.

> #### Time zones other than UTC {: .warning}
>
> When `date_time_or_zone` is a string and it is not `UTC` or `GMT`, a
> [Time Zone database](https://hexdocs.pm/elixir/DateTime.html#module-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
  `t: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 `t: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> {:ok, time} = DateTime.new(~D[2025-01-01], ~T[00:00:00], "Canada/Newfoundland")
    iex> Cldr.DateTime.Timezone.gmt_format(time, locale: :ar)
    {:ok, "غرينتش-03: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`
*since 2.23.0* 

```elixir
@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 `t:DateTime.t/0`.

> #### Time zones other than UTC {: .warning}
>
> When `date_time_or_zone` is a string and it is not `UTC` or `GMT`, a
> [Time Zone database](https://hexdocs.pm/elixir/DateTime.html#module-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
  `t: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](https://en.wikipedia.org/wiki/ISO_8601#:~:text=Z%20is%20the%20zone%20designator,30Z%22%20or%20%22T0930Z%22.)
  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`

# `location_format`
*since 2.23.0* 

```elixir
@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 `t:DateTime.t/0`.

### Arguments

* `date_time_or_zone` is any time zone ID or any
  `t: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 `t: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`

# `non_location_format`
*since 2.23.0* 

```elixir
@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 `t:DateTime.t/0`.

### Arguments

* `date_time_or_zone` is any time zone ID or any
  `t: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 `t: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`
*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 `t: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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*