Skip to content

Latest commit

 

History

History
204 lines (127 loc) · 6.49 KB

README.md

File metadata and controls

204 lines (127 loc) · 6.49 KB
Raw
sidebar
auto

The tzdb version repository

About

All software packages read a set of JSON files to calculate the changes between timezone versions. These files are generated by the a0-tzmigration-ruby gem, and are publicly available in the official repository here:

https://a0.github.io/a0-tzmigration-ruby/data/

When you create a new TZVersion instance and query something about it, a corresponding JSON file will be downloaded. This means that your system must have access to the URL above, or things will not work. For example:

tzversion = A0::TZMigration::TZVersion.new('Africa/Dakar', '2013c')
puts tzversion.data()

When you call tzversion.data(), it will start a download for the following url:
https://a0.github.io/a0-tzmigration-ruby/data/timezones/Africa/Dakar.json

This JSON timezone file is automatically downloaded on demand when needed, and cached by every TZVersion instance.

The Timezone JSON structure

The contents of the Africa/Dakar.json file look something like this:

{ "name": "Africa/Dakar",
  "versions": {
    "2013c": {
      "tag": "v1.2013.3",
      "released_at": "2013-04-19 16:17:40 -0700",
      "transitions": [
        { "utc_offset": -3600,
          "utc_prev_offset": -4184,
          "utc_timestamp": -1830379816,
          "utc_time": "1912-01-01T01:09:44+00:00",
          "local_ini_str": "1912-01-01 00:00:00 LMT",
          "local_fin_str": "1912-01-01 00:09:44 WAT"
        }
      ]
    },
    "2014f": {
      "tag": "v1.2014.6",
      "released_at": "2014-08-05 17:42:36 -0700",
      "alias": "Africa/Abidjan"
    }
  }
}

name

  • Type: string

The name of the timezone, for ex: "Africa/Dakar"

versions

  • Type: dictionary

A dictionary of known versions available for this timezone, where the key is the official tzdb version like 2014f. The object for that key is returned when you call tzversion.version_data() on a TZVersion instance.

tag

  • Type: string

The git tag from the tzinfo-data gem where this version data came from, for example v1.2014.6.

released_at

  • Type: date string

The Official tzdb date release of this version which is extracted from the NEWS file, for example "2014-08-05 17:42:36 -0700".

transitions

  • Type: array

An ordered list of transitions. Each transition represents a switch of local clocks in this timezone.

utc_time

  • Type: iso 8610 date string

The time at which this transitions occurrs.

utc_timestamp

  • Type: number

The same time as above at which this transitions occurs, but as an UNIX timestamp, ie: seconds since the epoch ignoring leap seconds.

local_ini_str, local_fin_str

  • Type: local time, varies

The local time at which this transitions occurs. For ex: "1912-01-01 00:00:00 LMT" and "1912-01-01 00:09:44 WAT" means: at 1 of January 1912 midnight, set your clocks forward to 09:44.

LMT usually means Local Mean Time. Other abreviations like WAT, PET, CLT, etc are no longer used anymore in recent tzdb releases, so use this fields for informational purposes only.

utc_offset

  • Type: number

The number of seconds the local time differs from UTC when this transition occurs. For ex: -3600 means UTC-01.

utc_prev_offset

  • Type: number

The number of seconds the local time differs before this transition occurs.

alias

  • Type: string

Sometimes a timezone doesn't have any transitions in their own, because it uses the transitions from another zone. Like Chile/Continental is a link or alias to America/Santiago.

Never asume an alias is permanent, ie: always look in the version_data object to find out. In the Africa/Dakar timezone for example, it became an alias only since the 2014f tzdb version.

When you call tzversion.version_data() on an instance, it will automatically download the linked zone for you, so it returns the version_data corresponding to the aliased zone.

The Timezones index JSON structure

You can programatically fetch the current known time zones with the following example code:

timezones = A0::TZMigration::TZVersion.timezones()
puts timezones

This will start a download for the following url:
https://a0.github.io/a0-tzmigration-ruby/data/timezones/00-index.json

This file is never cached, so you always get a fresh version from the repository. The contents of the timezones/00-index.json file look something like this:

{ "timezones": {
    "Africa/Abidjan": { "versions": [ "2013c", "2013d", "2013e", … ,"2018e"] },
    "Africa/Accra": { "versions": [ "2013c", "2013d", "2013e", … ,"2018e"] },
    …
  }
}

As you can see, you can use this index to build a UI, like the Demo at this site.

timezones

  • Type: dictionary

The dictionary with the current timezones availables, each key is the name of the timezone.

versions

  • Type: array

An array which contains all currently known tzdb versions available for this timezone.

The Versions index JSON structure

You can programatically fetch the current known versions with the following example code:

versions = A0::TZMigration::TZVersion.versions()
puts versions

This will start a download for the following url:
https://a0.github.io/a0-tzmigration-ruby/data/versions/00-index.json

This file is never cached, so you always get a fresh version from the repository. The contents of the versions/00-index.json file look something like this:

 { "versions": {
     "2013c": { 
       "released_at": "2013-04-19 16:17:40 -0700",
       "timezones": [ "Africa/Abidjan","Africa/Accra","Africa/Addis_Ababa","Africa/Algiers", …
}

This is useful to known wether a new version is available at the repo.

versions

  • Type: dictionary

The dictionary with the current versions availables, each key is the name of the version.

released_at

  • Type: date string

The Official tzdb date release of this version which is extracted from the NEWS file, for example "2014-08-05 17:42:36 -0700".

timezones

  • Type: array

An array which contains all currently known timezones available for this version.