Core Concepts: How It Works

This project combines data from OpenStreetMap (OSM) with a set of defined rules to create accurate timezone boundaries. The process is orchestrated by the main script (index.js) and defined by three core configuration files.

Data Flow

The build process follows these general steps:

  1. Data Fetching: The script begins by downloading all required geographical boundaries from OpenStreetMap using the Overpass API. The specific queries for these boundaries are defined in osmBoundarySources.json.

  2. Geometric Construction: For each timezone identifier (e.g., America/New_York), the script follows a series of steps defined in timezones.json. It starts with an initial shape and then applies a sequence of geometric operations (union, difference, intersection) with other shapes to carve out the final boundary.

  3. Post-Processing: Once a timezone boundary is constructed, it undergoes post-processing to clean up the geometry. This includes:

    • Reducing the precision of coordinates to decrease file size.
    • Removing tiny, insignificant holes and exclaves (polygons with an area less than 1 square meter).

  4. Validation: A critical step is validation. The script checks every timezone boundary against every other boundary to ensure there are no overlaps. Certain overlaps in disputed territories are permitted, as defined in expectedZoneOverlaps.json.

  5. Adding Oceans: A separate process generates boundaries for oceanic timezones (e.g., Etc/GMT-5). It does this by creating large longitudinal slices of the globe and subtracting all land-based timezones from them.

  6. Packaging Releases: Finally, the script generates multiple release bundles by combining the generated boundaries in different ways, as detailed in the Release Data Explained guide. This includes creating GeoJSON and Shapefile outputs, both with and without oceans, and for different timekeeping similarities.

Geometric Operations

The construction of each timezone relies on a few fundamental geometric operations performed using the jsts library:

  • init: Initializes the geometry for the timezone. This is always the first operation and typically uses a large boundary like a country or a state.
  • union: Combines the current geometry with another shape. This is used to add an area to the timezone.
  • difference: Subtracts another shape from the current geometry. This is used to cut out an area (e.g., to create a boundary with a neighboring timezone).
  • intersect: Calculates the common area between the current geometry and another shape. This is used to limit a timezone to a specific region (e.g., a timezone that only exists within a particular state).

By chaining these simple operations, complex and accurate boundaries can be built from simpler, well-defined shapes sourced from OpenStreetMap.