Timezone Boundary Builder: Mapping the World’s Timezones with OpenStreetMap

Imagine a globe where every minute of every location is labeled with its correct local time in a way that machines and maps can understand. That’s the purpose behind the Timezone Boundary Builder: to produce a shapefile (and other data products) that delineate the world’s timezones using data drawn from OpenStreetMap. This blog explores what the project does, how it releases data, and how you can work with it, all grounded in the practical details and visuals provided by the project’s materials.

Release data in this project is made available through the releases section of the repository, and the project maintains a clear relationship with the timezone database maintained by the IANA. To give you quick access to release activity, you’ll often see the GitHub badges at the top of pages and releases:

Release data and documentation are central to how this project communicates changes, boundaries, and new timekeeping methods. The releases have been available since October 2016, and each release carries a note about how it aligns with or diverges from official timezone data.

Release data and its purpose

• The Release data section of the project explains that the boundaries are constructed to approximate the world’s timezones and are associated with a single tzid, as defined by the timezone database (for example, America/Los_Angeles or Asia/Shanghai).
• Each shape or GeoJSON object includes a single tzid attribute, ensuring a straightforward mapping from geography to timekeeping.
• The release process aims to stay synchronized with the timezone database, creating new releases when a new timezone is added or deprecated, or when boundary definitions require updates due to bug fixes or new features.
• There are three primary dimensions of variation for release data, described in detail below, which together determine the exact data product you download.

The three axes of variation in releases

As of release 2023d, timezone boundary data is generated in three dimensions, yielding multiple product variations. Each dimension influences the structure and interpretation of the resulting timezones.

1) Similarity of timekeeping method

There are three sub-variations that describe how the project treats timekeeping history:

• Comprehensive
• Same since 1970
• Same since now

Comprehensive

This approach includes all timezone identifiers that the timezone database historically produced, following the old practice of one zone per country and including zones that have credible historical data. It aims to reflect the pre-1970 era as accurately as possible, accounting for data that the timezone database may mark as deprecated but still relevant for certain analyses. The comprehensive dataset is the foundation used to produce the other two timekeeping variations. In the releases, you’ll see prefixes like timezones or timezones-with-oceans for these datasets. A representative image of the comprehensive approach is shown here:

Same since 1970

This variant merges timezones that have maintained consistent timekeeping since 1970, resulting in a smaller set of zones and simpler polygons. It relies on the tubular/time library to determine which zones should be merged, choosing the representative tzid by the city with the largest population within the merged group. This approach aligns with the timezone database’s official stance that timekeeping methods considered “the same since 1970” are the authoritative baseline. The generated zones are labeled with prefixes timezones-1970 or timezones-with-oceans-1970 in the release files.

Same since now

This variation merges zones that agree on timekeeping methods as of the approximate release date of the data. It emphasizes current or future time at a location and is useful for applications that don’t require historical accuracy prior to the present. As with the 1970 variant, it uses the largest city population to select the tzid for merged zones. The release files carry the prefixes timezones-now or timezones-with-oceans-now.

2) With or without oceans

In conjunction with timekeeping variations, data products come in two ocean-related flavors:

• Without oceans
• With oceans (covering the oceans from Etc/GMT+12 to Etc/GMT-12)

A common misconception is about the Etc/GMT zones; the timezone database clarifies that these are not “east-to-west” in the conventional sense. The naming convention is designed to be consistent with POSIX TZ settings, which can be counterintuitive in everyday intuition. For example, TZ='Etc/GMT+4' corresponds to 4 hours behind UT, i.e., west of Greenwich. The oceans-include variations are explicitly marked with the with-oceans string in the file names, and data with or without oceans was first made available in release 2018d. As of release 2025c, oceans are merged in a way that respects similar timekeeping methods.

3) GeoJSON or Shapefile

The final dimension of variation concerns the file format:

• GeoJSON
• Shapefile

Each combination is released as a zip file, with formats indicated by their extensions in the file names (for example, .geojson.zip or .shapefile.zip). This flexibility allows developers and analysts to pick the toolchain that best fits their workflows, whether they prefer geo-enabled databases, GIS software, or web mapping libraries.

Supplementary files and input data

Every release contains supplementary files that help users understand and reproduce the data:

• A list of all timezone identifiers included in the data release (timezones.json style). This was added to the releases starting in 2019b and expanded in 2025c to differentiate between ocean and non-ocean zones.
• The input data used to assemble the releases (starting with release 2020a). This includes the raw data from OpenStreetMap and the project’s internal definitions at the release time.
• Timezone names files (timezone-names) that enumerate the timezone identifiers included in each dataset. The format differs by release, but the purpose is to provide a readable map of the included timezones. The comprehensive data uses a simple array of identifiers, while later releases differentiate ocean vs. non-ocean zones in the listing.
• input-data.zip containing the raw and cached data used to generate the timezone boundaries, including the Overpass outputs and internal configuration files (osmBoundarySources.json, timezones.json) and, as of 2023d, cached data to speed recomputation.

These supplementary files are designed to give researchers and developers the context they need to understand how the boundaries were built and to replicate or audit the process if needed.

Source of the data

At the heart of the project is data sourced from OpenStreetMap (OSM) via the Overpass API. The workflow combines different boundary sets to produce each timezone boundary, applying a range of geographic operations. Edge cases can yield unusual boundaries, especially in sparsely populated or international waters, and the project documents these caveats in the timezones.json file.

OpenStreetMap has a rich history of timezone-related data, including timezone relations that are sometimes piggy-backed on top of administrative boundaries. The project notes the discussions and changes in OSM’s handling of timezone relations and highlights resources such as the Key:timezone wiki page to guide contributors. The intent is to rely more heavily on primary timezone data from OpenStreetMap as quality and documentation continue to improve.

This approach keeps the project aligned with community-driven data, while maintaining a robust pipeline for quality control before release.

Lookup libraries and ecosystem

A wide ecosystem exists around the data produced by the Timezone Boundary Builder. Several libraries across languages and platforms provide APIs to look up the timezone at a given GPS coordinate using the project’s data. While I won’t enumerate every library here, a representative sample includes:

• C: ZoneDetect
• Elixir: tz_world
• Go: timezoneLookup
• Go: tzf
• Java & Android: TimeZoneMap
• Java: Timeshape
• JavaScript (Node.js only): node-geo-tz
• JavaScript (Node.js and browser): timespace
• JavaScript (Node.js and browser): tz-lookup
• JavaScript (browser only): browser-geo-tz
• JavaScript (WASM): tzf-wasm
• Julia: TimeZoneFinder
• .NET: GeoTimezone
• .NET: TZFinder
• Perl: Geo::Location::TimeZoneFinder
• PHP: Geo-Timezone
• Python: timezonefinder
• Python: tzfpy
• R: lutz
• Ruby: tzf-rb
• Ruby: wheretz
• Rust: tzf-rs
• Rust: rtz
• Swift: tzf-swift

These libraries illustrate how the data can be deployed in various environments, from server-side services to client-side applications, and how shapefile data can be imported into spatial databases for further analysis. A common pattern is to load the output into a geographic information system (GIS) or to query the tzid for a given coordinate.

If you’re exploring this data for a larger data warehouse or a live API, you can also consult related blog posts and examples, such as how others have used shapefiles in spatial databases to deliver faster, scalable time-zone lookups.

Running the script to generate timezones

If you want to generate timezones locally, the project provides a script that pulls OSM data, merges boundaries, and outputs timezones in your chosen formats. It’s worth noting that OpenStreetMap data is dynamic, so building the latest boundaries can be sensitive to changes in OSM data and the Overpass API.

• The script can generate timezones for all zones using: node --max-old-space-size=8192 index.js

• To restrict to specific zones, you can include an inclusion list: node --max-old-space-size=8192 index.js --includedzones America/NewYork America/Chicago

• To exclude certain zones: node --max-old-space-size=8192 index.js --excludedzones America/NewYork America/Chicago

• You can customize where files are downloaded, stored, and written: node --max-old-space-size=8192 index.js --downloadsdir ./downloads2 --distdir ./dist2 --working_dir ./working2

The project exposes a broad set of flags to tailor the build. For example:

• --help: Show basic usage
• --cache_dir: Directory for cached calculation files (default ./cache)
• --dist_dir: Directory for release files (default ./dist)
• --downloads_dir: Directory for raw downloaded files (default ./downloads)
• --excluded_zones: A list of timezones to exclude during build
• --included_zones: An allow-list of zones to include (if used with exclusions, exclusions apply to this list)
• --skip1970zones: Skip zones with “same since 1970” method
• --skipnowzones: Skip zones with “same since now” method
• --skipanalyzediffs: Skip analyzing differences versus the previous release
• --skipanalyzeosmtzdiffs: Skip downloading OSM data for unused timezone relations and skip diff analysis
• --skip_shapefile: Skip creating a shapefile output
• --skip_validation: Skip validation checks
• --skip_zip: Skip zipping of releases
• --working_dir: Directory for intermediate calculations

Behind the scenes, three config files guide the script:

• osmBoundarySources.json: Lists the Overpass queries that define which boundaries to extract
• timezones.json: Lists all timezones and the operations to apply
• expectedZoneOverlaps.json: Defines acceptable overlaps between zones and their bounds

The index.js file orchestrates the entire process: downloading geometries, building and validating boundaries, analyzing diffs, producing a huge GeoJSON, and zipping the results. If you want to reproduce a release as it appeared, you can also use the input-data.zip included in releases, which contains the data used at the time of the release, plus cached data to speed the process.

The script is designed to be run on Node.js 10 for compatibility with certain environments. It includes a throttling mechanism to respect the Overpass API’s rate limits, spacing requests by at least four seconds and increasing the gap if the API throttles again.

If you want to dig deeper into the troubleshooting process, the project’s troubleshooting guide is a valuable resource for common errors and strategies to resolve them.

Limitations of the project

• The data relies heavily on OpenStreetMap, an open, editable resource. This means some borders are a matter of interpretation or chosen boundaries, especially in oceanic areas or sparsely populated islands.
• Some ocean boundaries are approximated, focusing on territorial waters rather than Exclusive Economic Zones (EEZs).
• Timezone boundaries can reflect changes that are debated or still evolving in the wider community. The project’s release process is designed to document these nuances, but it’s important to understand their implications for historical analyses versus current-time use.

Contributing and community involvement

Contributions are welcomed. The project emphasizes:

• Improvements to code with attention to quality and maintainability
• Changes to timezone boundary configurations should include a solid justification and, if possible, links to public documents describing observed boundaries
• Any changes affecting observed time should be communicated to the timezone database
• A linting script verifies the integrity of timezones.json, osmBoundarySources.json, and expectedZoneOverlaps.json, and ensures necessary Overpass sources are defined

If an operation uses manual geometry, a description is required. Every time overlap must have a justification in the documentation.

Acknowledgments

The project expresses gratitude to those who have contributed to the timezone database and to OpenStreetMap contributors for their ongoing work that makes this boundary builder possible. Special thanks go to OpenStreetMap contributors, particularly Shinigami for work on timezone boundaries, Björn Harrtell for his contributions to geometry libraries, and the broader timezone database community for their ongoing guidance and data.

Licensing

• The code used to construct timezone boundaries is licensed under the MIT License.
• The produced timezone boundary data is licensed under the Open Data Commons Open Database License (ODbL).

Closing thoughts

The Timezone Boundary Builder represents a practical fusion of open data, geospatial processing, and timekeeping history. By combining OpenStreetMap’s boundary data with a careful release strategy that mirrors, yet sometimes refines, official timezone definitions, the project provides a robust resource for developers, researchers, and GIS professionals. It is a living project—one that acknowledges the evolving nature of timekeeping across regions and the ever-changing world map.

To get a feel for the different release styles and what they look like in practice, you can compare the visuals for the three “Same since” variants with the comprehensive baseline, noting how each alters polygon shapes and tzid assignments. The visuals below illustrate the three core timekeeping philosophies:

• Comprehensive approach: a broad, historically informed map of boundaries (image reference: 2026c.png).
• Same since 1970: a simplified map that reflects long-standing timekeeping practices (image reference: 2026c-1970.png).
• Same since now: a current-forward map that emphasizes present-day timekeeping (image reference: 2026c-now.png).

As you work with the data, you’ll also encounter the ocean-inclusive variations, the GeoJSON outputs, and the shapefile products—each crafted to support different workflows, from web services to GIS analysis. For anyone building a global time-aware application, these releases provide a dependable, well-documented foundation, backed by a lively ecosystem of lookup libraries across languages and platforms.

If you’re curious to explore further, the project’s releases and supplementary files offer a treasure trove of data and context. You’ll find the history of releases, the diverse data products, the sources of data, and the community-driven ethos that keeps this work both useful and up-to-date. Whether you’re a developer integrating timezones into a global app, a GIS analyst modeling regional timekeeping, or a researcher studying how time is defined across borders, the Timezone Boundary Builder provides a thoughtful, well-documented pathway to reliable, machine-readable timezone boundaries.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/timezone-boundary-builder?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)