Skip to main content

TimeZoneListResponse

List of time zones with localized information

  • Array [
  • abbreviationstringrequired

    Time zone abbreviation (e.g., 'CST', 'CDT').

    aliasesstring[]required

    An array of aliases (e.g. ['US/Central']).

    canonicalbooleanrequired

    Whether this is the canonical time zone identifier in the IANA database.

    dstbooleanrequired

    Whether daylight saving time is currently active.

    formatted_offsetstringrequired

    Human-readable offset (e.g., '-06:00').

    generic_long_namestringrequired

    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.

    goldenbooleanrequired

    Whether the time zone is considered a golden zone in the CLDR database.

    idstringrequired

    The identifier for the IANA Time Zone Database, also known as the Olson database (e.g. America/Chicago).

    legacybooleanrequired

    Whether the time zone is a "legacy" zone that does not conform to the standard Olson identifier format.

    long_namestringrequired

    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 objectnullable

    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.

    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.
    exemplar_citystringnullable

    The exemplar city designated for the metazone, if applicable (e.g. Chicago).

    long objectnullable

    A collection of generic and DST-specific "long" names (some or all might be null).

    currentstringnullable
    daylightstringnullable
    genericstringnullable
    standardstringnullable
    namestring

    The identifier for the metazone (e.g. America_Central).

    short objectnullable

    A collection of generic and DST-specific "short" names (some or all might be null).

    currentstringnullable
    daylightstringnullable
    genericstringnullable
    standardstringnullable
    territoriesstring[]

    Territory codes that use this metazone.

    offsetintegerrequired

    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_stdintegerrequired

    The number of seconds offset from standard time (this will be zero when in standard time, and non-zero when in daylight saving time).

    offset_utcintegerrequired

    The number of seconds offset from UTC (when in standard time).

    period objectrequired

    The boundaries of the current zone period (e.g. either standard time or daylight saving time).

    fromdate-timenullable

    When the current period started.

    untildate-timenullable

    When the current period ends.

    windows_zone objectnullablerequired

    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.

    namestring

    Windows time zone name

  • ]
  • TimeZoneListResponse
    [
    {
    "abbreviation": "CST",
    "aliases": [
    "US/Central"
    ],
    "canonical": true,
    "dst": false,
    "formatted_offset": "-06:00",
    "generic_long_name": "Central Time",
    "golden": true,
    "id": "America/Chicago",
    "legacy": false,
    "long_name": "Central Standard Time",
    "metazone": {
    "exemplar_city": null,
    "long": {
    "current": "Central Standard 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": -21600,
    "offset_std": 0,
    "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"
    }
    },
    {
    "abbreviation": "CST",
    "aliases": [
    "US/Central"
    ],
    "canonical": true,
    "dst": false,
    "formatted_offset": "-06:00",
    "generic_long_name": "Central Time",
    "golden": true,
    "id": "America/Chicago",
    "legacy": false,
    "long_name": "Central Standard Time",
    "metazone": {
    "exemplar_city": null,
    "long": {
    "current": "Central Standard 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": -21600,
    "offset_std": 0,
    "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"
    }
    }
    ]