IANA Time Zone Data for North America

Common errors

• TypeError: Cannot read properties of undefined (reading 'America/New_York') or similar `TypeError` when accessing a zone

  cause The module was not correctly imported or loaded, or you are trying to access a time zone that does not exist in the loaded data.
  fix Ensure `import jsonData from 'tzdata-northamerica';` or `const jsonData = require('tzdata-northamerica');` is correctly executed and that `jsonData` holds the expected object. Verify the time zone string (e.g., 'America/New_York') is spelled correctly and is part of the North American dataset.

• tzdataNorthamerica is not defined

  cause When used in a browser, the UMD script `tzdata-northamerica.js` was not loaded correctly or executed before your accessing script, or the path to the script was incorrect.
  fix Ensure the `<script src="./node_modules/tzdata-northamerica/tzdata-northamerica.js"></script>` tag is present in your HTML *before* the script that tries to access `tzdataNorthamerica`. Check the file path to ensure it points to the correct location of the UMD bundle.

• Expected time zone 'Europe/Berlin' but got 'undefined' when accessing `jsonData['Europe/Berlin']`

  cause You are attempting to retrieve data for a time zone that is not part of the North America-specific dataset provided by this package.
  fix This package only contains IANA zones from North America. If you need data for other regions, use the main `tzdata` package or other regional `tzdata-*` packages (e.g., `tzdata-europe`).

Warnings

• breaking The underlying IANA TZ Database is updated frequently to reflect geopolitical changes (e.g., new DST rules, standard time zone offsets, changes in political boundaries affecting time). These data updates, while not code-breaking, can alter time calculations for past and future dates if your application relies on specific historical zone data. For example, `v1.0.40` (tzdata 2024a) included significant changes for Kazakhstan and Palestine.
  Fix: Always use the latest version of `tzdata-northamerica` to ensure the most accurate and up-to-date time zone information. Be aware that time zone calculations using previous versions of the data may yield different results. Regularly review IANA TZDB release notes for significant changes.
• gotcha This package is a *subset* of the full IANA TZ database, containing only zones from the 'northamerica' file (e.g., America/New_York, Pacific/Honolulu). It does not contain time zone data for other continents or regions like Europe, Asia, or Africa.
  Fix: If your application requires global time zone data, you should install the main `tzdata` package or combine specific regional packages like `tzdata-europe`, `tzdata-asia`, etc., as needed. Do not assume `tzdata-northamerica` provides comprehensive global coverage.
• gotcha This package provides raw time zone *data* (a JSON object) and does not include any logic or functions for performing time zone calculations (e.g., converting dates, determining offsets for a given timestamp, formatting).
  Fix: You must use this data in conjunction with a dedicated time zone library (e.g., `timezonecomplete`, `luxon`, `moment-timezone`) that can interpret the IANA TZDB format and perform date/time manipulations. This package is solely a data source for such libraries.

Install

• npm install tzdata-northamerica npm
• yarn add tzdata-northamerica yarn
• pnpm add tzdata-northamerica pnpm

Imports

• jsonData
  wrong:

  const jsonData = require('tzdata-northamerica');

  correct:

  import jsonData from 'tzdata-northamerica';

  For Node.js, the package exports the JSON data object as its default export. While CommonJS `require` is shown in the README, ESM `import` is the modern approach and generally works for JSON modules or CJS modules that export a single object. Avoid `import { someProperty } from 'tzdata-northamerica'` as there are no named exports.
• tzdataNorthamerica

  <!-- In HTML: <script src="./node_modules/tzdata-northamerica/tzdata-northamerica.js"></script> -->
  <script>
      function onLoad() {
          const data = tzdataNorthamerica;
          console.log('Loaded North America TZ data in browser.');
      }
  </script>

  For browser usage, including the UMD bundle script in your HTML creates a global variable `tzdataNorthamerica` which holds the time zone data.

Quickstart

This quickstart demonstrates how to import and access time zone data for North American zones in a Node.js environment. It shows how to retrieve the raw JSON data for specific zones like 'America/New_York' and 'America/Los_Angeles', and illustrates that non-North American zones will not be present in this package. It also hints at how this data would be integrated with a time zone calculation library.

import jsonData from 'tzdata-northamerica';

// Access specific time zone data by IANA name
const newYorkData = jsonData['America/New_York'];
const losAngelesData = jsonData['America/Los_Angeles'];

console.log('--- Time Zone Data for America/New_York ---');
if (newYorkData) {
  // The data structure is an object where keys might represent years or rule sets.
  // This example just shows a simplified view of its content.
  console.log(`America/New_York data is available. It has ${Object.keys(newYorkData).length} top-level entries.`);
  const firstKey = Object.keys(newYorkData)[0];
  if (firstKey) {
    console.log(`First entry for America/New_York (key: ${firstKey}):`, newYorkData[firstKey]);
  }
} else {
  console.log('Error: America/New_York data not found. This should not happen with tzdata-northamerica.');
}

console.log('\n--- Time Zone Data for America/Los_Angeles ---');
if (losAngelesData) {
  console.log(`America/Los_Angeles data is available. It has ${Object.keys(losAngelesData).length} top-level entries.`);
} else {
  console.log('Error: America/Los_Angeles data not found. This should not happen with tzdata-northamerica.');
}

// Attempting to access a non-North American zone will result in undefined
const berlinData = jsonData['Europe/Berlin'];
console.log('\nAttempting to access Europe/Berlin (not in this package):', berlinData);
// Expected output for Berlin: undefined

// To use this data meaningfully, typically you'd pass it to a library like timezonecomplete.
// Example (conceptual, requires timezonecomplete setup):
// import { TzDatabase, DateTime } from 'timezonecomplete';
// TzDatabase.init([jsonData]); // Initialize with the loaded data
// const nowInNYC = new DateTime('now', 'America/New_York');
// console.log('Current time in New York (conceptual):', nowInNYC.toString());