Release Data Explained

As of release 2023d, this project produces timezone boundary data products with three different variations:

  1. Similarity of timekeeping method
  2. With or without oceans
  3. GeoJSON or Shapefile

Additionally, the input data used to assemble the releases and a list of timezone names are also included in each release.

1. Similarity of timekeeping method

There are 3 different timekeeping similarity variations that are produced:

  • Comprehensive
  • Same since 1970
  • Same since now

Comprehensive

This follows a strategy of including all timezone identifiers that were produced by the timezone database project according to the up-until 1993 practice of producing at least one zone per country. This does not include zones that were determined to be unnecessary due to lack of supporting evidence. This variation should mostly align with those timezones listed in the zone.tab file within the timezone database project. This dataset is the basis for producing the other 2 timekeeping variations in this project.

This output variation provides data that assumes that some data about time changes prior to 1970 marked as deprecated within the timezone database is actually correct. Depending on whether the data prior to 1970 within the timezone database is deemed correct, then the use of this dataset will provide as comprehensive as possible data for observed timekeeping methods worldwide.

In the release files, these zones are identified with the prefix timezones or timezones-with-oceans. This was how timezones were originally published by this project and has backwards compatibility with the methodology used to produce timezone database releases since this project started.

Same since 1970

This strategy merges timezones that have agreed on timekeeping methods since the year 1970. This results in a reduced set of timezones, simplified timezone polygons and smaller storage footprint. This variation should mostly align with those timezones listed in the zone1970.tab file within the timezone database project. However, the @tubular/time library is used to determine which zones get merged together from the comprehensive variation. The output of the zones from the comprehensive method are combined together for all relevant zones with the zone having the largest city population being used for the tzid of the merged zone in the final output.

This output variation is technically the most authoritative dataset since the timezone database officially supports only timekeeping methods that have been the same since 1970. Depending on whether the data prior to 1970 within the timezone database is deemed correct, then the use of this dataset may provide potentially incorrect data for observed timekeeping methods prior to 1970 at certain locations.

In the release files, these zones are identified with the prefix timezones-1970 or timezones-with-oceans-1970. Data with the "Same since 1970" timekeeping method was first made available in release 2023d.

Same since now

This strategy merges timezones that agree on timekeeping methods as of the approximate release date of the data. This results in a reduced set of timezones, simplified timezone polygons and smaller storage footprint. This variation should mostly align with those timezones listed in the zonenow.tab file within the timezone database project. However, the @tubular/time library is used to determine which zones get merged together from the comprehensive variation. The output of the zones from the comprehensive method are combined together for all relevant zones and the zone with the largest city population is used in the final output.

This output variation is only suitable for use cases that need to know the current or future time at a location. It will provide potentially incorrect data for observed timekeeping methods in the past at certain locations.

In the release files, these zones are identified with the prefix timezones-now or timezones-with-oceans-now. Data with the "Same since now" timekeeping method was first made available in release 2023d.

2. With or without oceans

In combination with the timekeeping method variations, there are two additional variations based on the inclusion of ocean zones. The first variation does not include any ocean zones in the output. The second variation does include ocean zones in the output from Etc/GMT+12 to Etc/GMT-12.

A common misconception is that Etc/GMT* zones should increase from west to east, however, this is not the case as explained in the timezone database in the etcetera file:

# Be consistent with POSIX TZ settings in the Zone names,
# even though this is the opposite of what many people expect.
# POSIX has positive signs west of Greenwich, but many people expect
# positive signs east of Greenwich.  For example, TZ='Etc/GMT+4' uses
# the abbreviation "-04" and corresponds to 4 hours behind UT
# (i.e. west of Greenwich) even though many people would expect it to
# mean 4 hours ahead of UT (i.e. east of Greenwich).

In the release files, the files that have oceans are specifically noted as having them due to having the string with-oceans within the filename. Release files without this string do not have ocean data. Data with or without oceans was first made available in release 2018d.

3. GeoJSON or Shapefile

In combination with the timekeeping method and ocean variations, each of these combinations is outputted as either GeoJSON or a shapefile. In both cases, each of these release types are made available in a zip file.

In the release files, the files that are provided in GeoJSON have the suffix .geojson.zip. The shapefiles have the suffix .shapefile.zip. Release files have been provided in GeoJSON or as shapefiles in releases since this project started.

Other Release Files

timezone-names.json

This release file is simply a single array with the list of timezone identifiers used to create the comprehensive release of timezone data. This has been included in releases starting from release 2019b.

input-data.zip

Each release includes the input and cached data used to generate the timezone boundary files. This includes the raw data downloaded from OpenStreetMap and the definition files within this project at the time of the release. Additionally, as of 2023d it also includes the cached data to facilitate quicker recomputation. The preparation phase of each release is so far still manual and therefore may include files downloaded on different days. This has been included in releases starting from release 2020a.