Time Zones

The SavvyCal Time Zone API includes endpoints for fetching in-depth information about time zones, such as human-friendly names, UTC offsets, and exemplar cities.

Introduction

The data presented in this API is compiled from the IANA Time Zone Database and the Unicode CLDR Project. The IANA database is updated frequently and we automatically point to the latest version.

Here’s an example of the data returned for America/Chicago (a.k.a. Central Time):

{
  "abbreviation": "CST",
  "aliases": [
    "US/Central"
  ],
  "canonical": true,
  "dst": true,
  "formatted_offset": "-06:00",
  "generic_long_name": "Central Time",
  "golden": true,
  "id": "America/Chicago",
  "legacy": false,
  "long_name": "Central Daylight Time",
  "metazone": {
    "exemplar_city": "Chicago",
    "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"
  }
}

This data is useful for constructing human-friendly labels for time zones, such as:

(GMT-06:00) Central Daylight Time (Chicago)

For more details about some of the terminology used here (such as metazones), check out the Time Zone resource documentation.

Authentication

You may authenticate your requests via personal access tokens or OAuth access tokens (see Authentication for more information). You may use personal access token public keys for making requests from insecure environments (such as your JavaScript frontend).

Create a free account and head to Developer settings to generate your tokens.

List Time Zones

This endpoint allows you to list all canonical zones in the time zone database.

Parameters

Name	Type	Description
instant	string	An ISO-8601 string representing the date/time we should use to calculate offsets for time zones. Defaults to now.
include_legacy	boolean	When true, includes legacy zones. Defaults to false.

Response

We return the following special response headers:

Name	Description
x-tzdata-version	The version of the IANA Time Zone Database (e.g. 2022f)

The response body includes an array of Time Zone resources.

[
  {
    "abbreviation": "CST",
    "aliases": [
      "US/Central"
    ],
    "canonical": true,
    "dst": true,
    "formatted_offset": "-06:00",
    "generic_long_name": "Central Time",
    "golden": true,
    "id": "America/Chicago",
    "legacy": false,
    "long_name": "Central Daylight Time",
    "metazone": {
      "exemplar_city": "Chicago",
      "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"
    }
  }
]

Get Time Zone

This endpoint allows you to fetch data for single time zone. The id should be an IANA time zone identifier (e.g. America/Los_Angeles). If the given id is an alias for a canonical time zone (for example, US/Central which is an alias for America/Chicago), we’ll automatically return the canonical zone information.

Parameters

Name	Type	Description
instant	string	An ISO-8601 string representing the date/time we should use to calculate offsets for time zones. Defaults to now.

Response

We return the following special response headers:

Name	Description
x-tzdata-version	The version of the IANA Time Zone Database (e.g. 2022f)

The response body includes a Time Zone resource.

{
  "abbreviation": "CST",
  "aliases": [
    "US/Central"
  ],
  "canonical": true,
  "dst": true,
  "formatted_offset": "-06:00",
  "generic_long_name": "Central Time",
  "golden": true,
  "id": "America/Chicago",
  "legacy": false,
  "long_name": "Central Daylight Time",
  "metazone": {
    "exemplar_city": "Chicago",
    "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"
  }
}