Bug: 150202143

Clone this repo:
  1. f0df979 Android additions to timezone-boundary-builder am: 4fd94cfcf9 am: 1d4954a75e am: 416012905c am: 82d8ad561d by Neil Fuller · 2 years, 10 months ago aml_tz4_332714010 aml_tz5_341510010 android13-d2-release android13-d3-s1-release android13-d4-release android13-d4-s1-release android13-d4-s2-release android13-dev android13-frc-adbd-release android13-frc-art-release android13-frc-cellbroadcast-release android13-frc-conscrypt-release android13-frc-odp-release android13-mainline-adservices-release android13-mainline-appsearch-release android13-mainline-go-adbd-release android13-mainline-go-adservices-release android13-mainline-go-appsearch-release android13-mainline-go-media-swcodec-release android13-mainline-go-mediaprovider-release android13-mainline-go-networking-release android13-mainline-go-neuralnetworks-release android13-mainline-go-odp-release android13-mainline-go-os-statsd-release android13-mainline-go-permission-release android13-mainline-go-resolv-release android13-mainline-go-scheduling-release android13-mainline-go-sdkext-release android13-mainline-go-tethering-release android13-mainline-go-tzdata4-release android13-mainline-go-uwb-release android13-mainline-go-wifi-release android13-mainline-tzdata4-release android13-mainline-uwb-release android13-qpr1-release android13-qpr1-s1-release android13-qpr1-s2-release android13-qpr1-s3-release android13-qpr1-s4-release android13-qpr1-s5-release android13-qpr1-s6-release android13-qpr1-s7-release android13-qpr1-s8-release android13-qpr2-b-s1-release android13-qpr2-release android13-qpr2-s1-release android13-qpr2-s10-release android13-qpr2-s11-release android13-qpr2-s12-release android13-qpr2-s2-release android13-qpr2-s3-release android13-qpr2-s5-release android13-qpr2-s6-release android13-qpr2-s7-release android13-qpr2-s8-release android13-qpr2-s9-release android13-qpr3-c-s1-release android13-qpr3-c-s10-release android13-qpr3-c-s11-release android13-qpr3-c-s12-release android13-qpr3-c-s2-release android13-qpr3-c-s3-release android13-qpr3-c-s4-release android13-qpr3-c-s5-release android13-qpr3-c-s6-release android13-qpr3-c-s7-release android13-qpr3-c-s8-release android13-qpr3-release android13-qpr3-s1-release android13-qpr3-s10-release android13-qpr3-s11-release android13-qpr3-s12-release android13-qpr3-s13-release android13-qpr3-s14-release android13-qpr3-s2-release android13-qpr3-s3-release android13-qpr3-s4-release android13-qpr3-s5-release android13-qpr3-s6-release android13-qpr3-s7-release android13-qpr3-s8-release android13-qpr3-s9-release android14-d1-release android14-d1-s1-release android14-d1-s2-release android14-d1-s3-release android14-d1-s4-release android14-d1-s5-release android14-d1-s6-release android14-d1-s7-release android14-dev android14-gsi android14-mainline-adservices-release android14-mainline-appsearch-release android14-mainline-healthfitness-release android14-mainline-uwb-release android14-platform-release android14-qpr1-release android14-qpr1-s2-release android14-qpr2-release android14-qpr2-s1-release android14-qpr2-s2-release android14-qpr2-s3-release android14-release android14-s1-release android14-s2-release android14-security-release android14-tests-release main main-16k main-16k-with-phones master aml_ads_331131000 aml_ads_331418080 aml_ads_331511020 aml_ads_331611190 aml_ads_331710270 aml_ads_331814200 aml_ads_331920180 aml_ads_340915050 aml_ads_341027030 aml_ads_341131050 aml_ads_341316030 aml_ads_341413000 aml_ads_341517040 aml_ase_331011020 aml_ase_331112000 aml_ase_331311020 aml_ase_340913000 aml_ase_341113000 aml_ase_341310010 aml_ase_341410000 aml_ase_341510000 aml_cfg_341510000 aml_go_adb_330913000 aml_go_ads_330913000 aml_go_ads_330915000 aml_go_ads_330915100 aml_go_ase_330913000 aml_go_mpr_330912000 aml_go_net_330913000 aml_go_neu_330912000 aml_go_odp_330912000 aml_go_odp_330913000 aml_go_per_330912000 aml_go_res_330912000 aml_go_sch_330911000 aml_go_sdk_330810000 aml_go_sta_330911000 aml_go_swc_330913000 aml_go_tet_330914010 aml_go_tz4_330912000 aml_go_uwb_330912000 aml_go_wif_330911000 aml_hef_341114030 aml_hef_341311010 aml_hef_341415040 aml_hef_341512030 aml_rkp_341012000 aml_rkp_341015010 aml_rkp_341114000 aml_rkp_341311000 aml_rkp_341510000 aml_tz4_331012000 aml_tz4_331012040 aml_tz4_331012050 aml_tz4_331314010 aml_tz4_331314020 aml_tz4_331314030 aml_tz4_331910000 aml_tz4_332714010 aml_tz4_332714050 aml_tz5_341510010 aml_tz5_341510050 aml_uwb_330810010 aml_uwb_331015040 aml_uwb_331115000 aml_uwb_331310030 aml_uwb_331410010 aml_uwb_331611010 aml_uwb_331613010 aml_uwb_331820070 aml_uwb_331910010 aml_uwb_341011000 aml_uwb_341111010 aml_uwb_341310030 aml_uwb_341310300 aml_uwb_341511050 android-13.0.0_r16 android-13.0.0_r17 android-13.0.0_r18 android-13.0.0_r19 android-13.0.0_r20 android-13.0.0_r21 android-13.0.0_r22 android-13.0.0_r23 android-13.0.0_r24 android-13.0.0_r27 android-13.0.0_r28 android-13.0.0_r29 android-13.0.0_r30 android-13.0.0_r32 android-13.0.0_r33 android-13.0.0_r34 android-13.0.0_r35 android-13.0.0_r36 android-13.0.0_r37 android-13.0.0_r38 android-13.0.0_r39 android-13.0.0_r40 android-13.0.0_r41 android-13.0.0_r42 android-13.0.0_r43 android-13.0.0_r44 android-13.0.0_r45 android-13.0.0_r46 android-13.0.0_r47 android-13.0.0_r48 android-13.0.0_r49 android-13.0.0_r50 android-13.0.0_r51 android-13.0.0_r52 android-13.0.0_r53 android-13.0.0_r54 android-13.0.0_r55 android-13.0.0_r56 android-13.0.0_r57 android-13.0.0_r58 android-13.0.0_r59 android-13.0.0_r60 android-13.0.0_r61 android-13.0.0_r62 android-13.0.0_r63 android-13.0.0_r64 android-13.0.0_r65 android-13.0.0_r66 android-13.0.0_r67 android-13.0.0_r68 android-13.0.0_r69 android-13.0.0_r70 android-13.0.0_r71 android-13.0.0_r72 android-13.0.0_r73 android-13.0.0_r74 android-13.0.0_r75 android-13.0.0_r76 android-13.0.0_r77 android-13.0.0_r78 android-13.0.0_r79 android-13.0.0_r80 android-13.0.0_r81 android-13.0.0_r82 android-13.0.0_r83 android-14.0.0_r1 android-14.0.0_r10 android-14.0.0_r11 android-14.0.0_r12 android-14.0.0_r13 android-14.0.0_r14 android-14.0.0_r15 android-14.0.0_r16 android-14.0.0_r17 android-14.0.0_r18 android-14.0.0_r19 android-14.0.0_r2 android-14.0.0_r20 android-14.0.0_r21 android-14.0.0_r22 android-14.0.0_r23 android-14.0.0_r24 android-14.0.0_r25 android-14.0.0_r26 android-14.0.0_r27 android-14.0.0_r28 android-14.0.0_r29 android-14.0.0_r3 android-14.0.0_r30 android-14.0.0_r31 android-14.0.0_r32 android-14.0.0_r33 android-14.0.0_r4 android-14.0.0_r5 android-14.0.0_r6 android-14.0.0_r7 android-14.0.0_r8 android-14.0.0_r9 android-cts-14.0_r1 android-cts-14.0_r2 android-cts-14.0_r3 android-platform-14.0.0_r1 android-platform-14.0.0_r2 android-platform-14.0.0_r3 android-platform-14.0.0_r4 android-platform-14.0.0_r5 android-platform-14.0.0_r6 android-security-14.0.0_r1 android-security-14.0.0_r2 android-security-14.0.0_r3 android-security-14.0.0_r4 android-security-14.0.0_r5 android-security-14.0.0_r6 android-security-14.0.0_r7 android-u-beta-1-gpl android-vts-14.0_r1 android-vts-14.0_r2 android-vts-14.0_r3 frc_340818110 frc_340818170 frc_340819010 frc_340819020 frc_340819030 frc_340819190 frc_340819220 frc_340819280 frc_340821000 t_frc_adb_330444000 t_frc_art_330443060 t_frc_ase_330444010 t_frc_cbr_330443000 t_frc_con_330443020 t_frc_odp_330442000 t_frc_odp_330442040
  2. 82d8ad5 Android additions to timezone-boundary-builder am: 4fd94cfcf9 am: 1d4954a75e am: 416012905c by Neil Fuller · 2 years, 10 months ago
  3. 4160129 Android additions to timezone-boundary-builder am: 4fd94cfcf9 am: 1d4954a75e by Neil Fuller · 2 years, 10 months ago android-s-qpr3-beta-1 android-s-v2-beta-3 android-s-v2-preview-1 android-t-preview-1 android-s-qpr3-beta-1 android-s-v2-beta-2 android-s-v2-beta-3 android-s-v2-preview-1 android-s-v2-preview-2 android-t-beta-3 android-t-preview-1 android-t-preview-2
  4. 1d4954a Android additions to timezone-boundary-builder am: 4fd94cfcf9 by Neil Fuller · 2 years, 10 months ago android-s-beta-4 android-s-beta-5 android-s-beta-3 android-s-beta-4 android-s-beta-5
  5. 4fd94cf Android additions to timezone-boundary-builder by Neil Fuller · 4 years ago

Timezone Boundary Builder

The goal of this project is to produce a shapefile with the boundaries of the world's timezones using OpenStreetMap data.

Github downloads for all releases GitHub release

Shapefiles and data

The shapefiles are available for download in this project's releases. As of release 2018d shapefiles are available with or without oceans. Each shape or geojson object has a single attribute or property respectively called tzid. The tzid corresponds to the timezone name as defined in the timezone database (for example: America/Los_Angeles or Asia/Shanghai).

This project aims to stay up-to-date with all of the currently valid timezones that are defined in the timezone database. This project also will attempt to provide the most accurate possible boundaries of timezones according to community input.

The underlying data is downloaded from OpenStreetMap via the overpass turbo API. Various boundaries are assembled together to produce each zone with various geographic operations. In numerous edge cases arbitrary boundaries get created in various zones which are noted in the timezones.json file.

To maintain consistency with the timezone database, this project will only create a new release after the timezone database creates a new release. If there are no new timezones created or deleted in a timezone database release, then this project will only create a release if there have been changes performed to the boundary definitions of an existing zone within this project.

Lookup Libraries

A few common languages already have libraries with an API that can be used to lookup the timezone name at a particular GPS coordinate. Here are some libraries that use the data produced by timezone-boundary-builder:

TimeZoneMapJava & Android
node-geo-tzJavaScript (node.js only)
timespaceJavaScript (node.js and in browser)
tz-lookupJavaScript (node.js and in browser)

Another common way to use the data for lookup purposes is to load the shapefile into a spatially-aware database. See this blog post for an example of how that can be done.

Running the script

If the data in the releases are not sufficiently recent or you want to build the latest from master, it is possible to run the script to generate the timezones. However, due to the ever-changing nature of OpenStreetMap, the script should be considered unstable. The script frequently breaks when unexpected data is received or changes in OpenStreetMap cause validation issues. Please see the troubleshooting guide for help with common errors.

Run the script to generate timezones for all timezones.

node --max-old-space-size=8192 index.js

Run the script to generate timezones for only specified timezones.

node --max-old-space-size=8192 index.js --included_zones America/New_York America/Chicago

Run the script to generate timezones while excluding specified timezones.

node --max-old-space-size=8192 index.js --excluded_zones America/New_York America/Chicago

Run the script with custom working / output directories.

timezone-boundary-builder downloads boundaries from OpenStreetMap and places them in the ./downloads directory by default. It generates output files in the ./dist directory by default.

If you want to use different directories, you can do so with the --downloads_dir and --dist_dir flags.

node --max-old-space-size=8192 index.js --downloads_dir ./downloads2 --dist_dir ./dist2

Other command line flags

Other command line flags:

  • --help - show some basic usage information
  • --skip_analyze_diffs - do not analyze differences between the current output and another version
  • --skip_shapefile - do not create the shapefile from the geojson file
  • --skip_validation - do not validate the time zone boundaries
  • --skip_zip - do not zip the generated geojson files

What the script does

There are three config files that describe the boundary building process. The osmBoundarySources.json file lists all of the needed boundaries to extract via queries to the Overpass API. The timezones.json file lists all of the timezones and various operations to perform to build the boundaries. The expectedZoneOverlaps.json file lists all timezones that are allowed to overlap each other and the acceptable bounds of a particular overlap.

The index.js file downloads all of the required geometries, builds the specified geometries, validates that there aren't large areas of overlap (other than those that are expected), analyzes the difference between the current output and the last release, outputs one huge geojson file, and finally zips up the geojson file using the zip cli and also converts the geojson to a shapefile using the ogr2ogr cli. The script has only been verified to run with Node.js 10 on the MacOS platform.

The code does query the publicly available Overpass API, but it self-throttles the making of requests to have a minimum of 4 seconds gap between requests. If the Overpass API throttles the download, then the gap will be increased exponentially.

The validation and difference analysis can take a really long time to compute. If these tasks are not needed, be sure to add the --skip_analyze_diffs and --skip_validation flags.

As of release 2020a, it is possible to run the script with the underlying input data that was used to build the timezone geometries at the time of the release. In the release files, the input-data.zip will have all of the necessary input data including the downloaded files from overpass, the timezones.json file and the osmBoundarySources.json file as well.

Limitations of this project

The data is almost completely comprised of OpenStreetMap data which is editable by anyone. There are a few guesses on where to draw an arbitrary border in the open waters and a few sparsely inhabited areas. Some uninhabited islands are omitted from this project. This project does include timezones in the oceans, but strictly uses territorial waters or Etc/GMT timezones instead of unofficially observed areas such as Exclusive Economic Zones.


Pull requests are welcome! Please follow the guidelines listed below:

Improvements to code

Will be approved subject to code review.

Changes to timezone boundary configuration

Any change to the boundary of existing timezones must have some explanation of why the change is necessary. If there are official, publicly available documents of administrative areas describing their timezone boundary please link to them when making your case. All changes involving an administrative area changing their observed time should instead be sent to the timezone database.

A linting script will verify the integrity of the timezones.json, osmBoundarySources.json and expectedZoneOverlaps.json files. The script verifies if all needed overpass sources are properly defined and that there aren't any unneeded overpass downloads. If an operation to make a timezone boundary requires the use of a manual geometry, a description must be added explaining the operation. All expected zone overlaps must have a description.


Thanks to following people whose open-source and open-data contributions have made this project possible:


The code used to construct the timezone boundaries is licensed under the MIT License.

The outputted data is licensed under the Open Data Commons Open Database License (ODbL).