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