Time Zone

The time zone includes a plethora of data information about a single IANA time zone definition.

Properties
Period
Metazones
Windows Zones
Example Payload

Properties

This resource includes the following properties:

Property	Type	Description
`abbreviation`	string	The time zone abbreviation (e.g. `CST`).
`aliases`	string[]	An array of aliases (e.g. `["US/Central"]`).
`canonical`	boolean	Whether the time zone is designated as “canonical” in the IANA database.
`dst`	boolean	Whether the time zone is in daylight saving time at the specified instant.
`formatted_offset`	string	The UTC offset formatted in hours/minutes at the specified instant (e.g. `-06:00`).
`generic_long_name`	string \| null	The generic name of the time zone’s metazone (absent of any daylight saving time modifiers). For example, the generic name for US Central Time is `Central Time`, whereas the non-generic is either `Central Daylight Time` or `Central Standard Time`, depending on the time of year.
`golden`	boolean	Whether the time zone is considered a “golden zone” in the CLDR database.
`id`	string	The identifier for the IANA Time Zone Database, also known as the Olson database (e.g. `America/Chicago`).
`legacy`	boolean	Whether the time zone is a “legacy” zone that does not conform to the standard Olson identifier format.
`long_name`	string	The most specific name for the time zone’s metazone, which may include daylight saving time modifiers at the specified instant. For example, the long name for US Central Time is either `Central Daylight Time` or `Central Standard Time`, depending on the time of year.
`metazone`	Metazone \| null	Information about the time zone’s metazone, if applicable.
`offset`	integer	The number of seconds offset from UTC at the specified instant. Note this may change depending on time of year, due to daylight saving time shifts.
`offset_utc`	integer	The number of seconds offset from UTC (when in standard time).
`offset_std`	integer	The number of seconds offset from standard time (this will be zero when in standard time, and non-zero when in daylight saving time).
`period`	Period	The boundaries of the current zone period (e.g. either standard time or daylight saving time).
`windows_zone`	Windows Zone \| null	The name of time zone specified in the Microsoft Windows zone file.

Period

The period object represents the boundaries of the current time period. A period ends when the offset changes (during the transition to and from standard time and daylight saving time).

Property	Type	Description
`from`	string \| null	An ISO-8601 datetime string represending when the period begins (will be `null` if there is no set beginning time).
`until`	string \| null	An ISO-8601 datetime string represending when the period ends (will be `null` if there is no set ending time).

For example, on June 1, 2022, the US Central Time zone was in daylight saving time. The period at that instant was as follows:

{
  "from": "2022-03-13T03:00:00-05:00",
  "until": "2022-11-06T02:00:00-06:00"
}

This indicates that DST began at 3:00 am on March 13 and ended at 2:00 am on November 11.

Metazones

A metazone is a collection of time zones that share the same behavior and same name during some period. Each metazone represents a geographic region and is useful for determining commonly-used names for time zones.

Property	Type	Description
`name`	string	The identifer for the metazone (e.g. `America_Central`).
`exemplar_city`	string \| null	The exemplar city designated for the metazone, if applicable (e.g. `Chicago`).
`long`	object	A collection of generic and DST-specific “long” names (some or all might be `null`).
`short`	object	A collection of generic and DST-specific abbreviations (some or all might be `null`).
`territories`	string[]	A list of territory codes.

For example, the metazone for U.S. Central Time is America_Central and has the following long and short identifiers defined in the Unicode CLDR repository:

{
  "name": "America_Central",
  "long": {
    "current": "Central Standard Time",
    "daylight": "Central Daylight Time",
    "generic": "Central Time",
    "standard": "Central Standard Time"
  },
  "short": {
    "current": "CST",
    "daylight": "CDT",
    "generic": "CT",
    "standard": "CST"
  },
  "territories": ["001"]
}

Some facts to note about metazones:

There are 126 metazones.
There are 93 metazones that map to a single time zone.
There are 34 metazones that map to multiple time zones. For example, the America_Central metazone includes 24 distinct time zones.
Every metazone has one golden zone, which “exemplifies” the metazone (and is tagged with territory "001").
There are 64 canonical time zones not associated with a metazone.

Windows Zones

Windows zones are names derived from the Microsoft Windows time zone mapping file (see windowsZones.xml in the CLDR repository). We use the zone names from this file as a fallback for long_name and generic_long_name fields when there does not exist a metazone name.

Property	Type	Description
`name`	string	The name used by the Windows operating system for the time zone (e.g. `Central Standard Time`).

Example Payload

Here is an example representation of this resource:

{
  "abbreviation": "CST",
  "aliases": [
    "US/Central"
  ],
  "canonical": true,
  "dst": true,
  "exemplar_city": "Chicago",
  "formatted_offset": "-06:00",
  "generic_long_name": "Central Time",
  "golden": true,
  "id": "America/Chicago",
  "legacy": false,
  "long_name": "Central Daylight Time",
  "metazone": {
    "long": {
      "current": "Central Daylight Time",
      "daylight": "Central Daylight Time",
      "generic": "Central Time",
      "standard": "Central Standard Time"
    },
    "name": "America_Central",
    "short": {
      "current": "CST",
      "daylight": "CDT",
      "generic": "CT",
      "standard": "CST"
    },
    "territories": ["001"]
  },
  "offset": -18000,
  "offset_std": 3600,
  "offset_utc": -21600,
  "period": {
    "from": "2022-03-13T03:00:00-05:00",
    "until": "2022-11-06T02:00:00-06:00"
  },
  "windows_zone": {
    "name": "Central Standard Time"
  }
}