README.md
1# Timezone Boundary Builder
2
3The goal of this project is to produce a shapefile with the boundaries of the world's timezones using OpenStreetMap data.
4
5<p align="center"><img src="2018i.png" /></p>
6
7[](https://www.somsubhra.com/github-release-stats/?username=evansiroky&repository=timezone-boundary-builder) [](https://github.com/evansiroky/timezone-boundary-builder/releases/latest)
8
9
10## Shapefiles and data
11
12The shapefiles are available for download in this project's [releases](https://github.com/evansiroky/timezone-boundary-builder/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](https://www.iana.org/time-zones) (for example: `America/Los_Angeles` or `Asia/Shanghai`).
13
14This 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.
15
16The underlying data is downloaded from [OpenStreetMap](http://www.openstreetmap.org/) via the [overpass turbo API](http://overpass-turbo.eu/). 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.
17
18To 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.
19
20## Lookup Libraries
21
22A 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:
23
24| Library | Language |
25| -- | -- |
26| [ZoneDetect](https://github.com/BertoldVdb/ZoneDetect) | C |
27| [go-tz](https://github.com/ugjka/go-tz) | Go |
28| [timezoneLookup](https://github.com/evanoberholster/timezoneLookup) | Go |
29| [TimeZoneMap](https://github.com/dustin-johnson/timezonemap) | Java & Android |
30| [Timeshape](https://github.com/RomanIakovlev/timeshape) | Java |
31| [node-geo-tz](https://github.com/evansiroky/node-geo-tz/) | JavaScript (node.js only) |
32| [timespace](https://github.com/mapbox/timespace) | JavaScript (node.js and in browser) |
33| [tz-lookup](https://github.com/darkskyapp/tz-lookup/) | JavaScript (node.js and in browser) |
34| [GeoTimezone](https://github.com/mj1856/GeoTimeZone) | .NET |
35| [Geo-Timezone](https://github.com/minube/geo-timezone) | php |
36| [timezonefinder](https://github.com/MrMinimal64/timezonefinder) | Python |
37| [lutz](https://github.com/ateucher/lutz) | R |
38
39Another common way to use the data for lookup purposes is to load the shapefile into a spatially-aware database. See this [blog post](https://simonwillison.net/2017/Dec/12/location-time-zone-api/) for an example of how that can be done.
40
41## Running the script
42
43If 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](https://github.com/evansiroky/timezone-boundary-builder/wiki/Troubleshooting) for help with common errors.
44
45**Run the script to generate timezones for all timezones.**
46
47```shell
48node --max-old-space-size=8192 index.js
49```
50
51**Run the script to generate timezones for only specified timezones.**
52
53```shell
54node --max-old-space-size=8192 index.js --filtered-zones "America/New_York,America/Chicago"
55```
56
57### What the script does
58
59There 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.
60
61The `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), 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.
62
63The 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.
64
65## Limitations of this project
66
67The 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.
68
69## Contributing
70
71Pull requests are welcome! Please follow the guidelines listed below:
72
73### Improvements to code
74
75Will be approved subject to code review.
76
77### Changes to timezone boundary configuration
78
79Any 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](https://www.iana.org/time-zones).
80
81A 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.
82
83## Thanks
84
85Thanks to following people whose open-source and open-data contributions have made this project possible:
86
87- All the maintainers of the [timezone database](https://www.iana.org/time-zones).
88- Eric Muller for constructing and maintaining the timezone shapefile at [efele.net](http://efele.net/maps/tz/world/).
89- The [OpenStreetMap contributor Shinigami](https://www.openstreetmap.org/user/Shinigami) for making lots of edits in OpenStreetMap of various timezone boundaries.
90- [Björn Harrtell](https://github.com/bjornharrtell) for all his work and help with [jsts](https://github.com/bjornharrtell/jsts).
91
92## Licenses
93
94The code used to construct the timezone boundaries is licensed under the [MIT License](https://opensource.org/licenses/MIT).
95
96The outputted data is licensed under the [Open Data Commons Open Database License (ODbL)](http://opendatacommons.org/licenses/odbl/).
97
){kind=link}
){kind=link}