{"id":16562,"library":"tzdata-northamerica","title":"IANA Time Zone Data for North America","description":"This package provides a machine-readable JSON representation of the 'northamerica' region from the official IANA Time Zone Database (TZDB). It is a pure data package, offering a static snapshot of time zone rules and historical offsets specific to North American regions, intended for consumption by time zone calculation libraries rather than performing computations itself. The current stable version, 1.0.48, reflects the IANA TZDB 2026a release. The package follows the IANA TZDB release cadence, typically updating several times a year to incorporate geopolitical changes to time zones (e.g., changes in DST rules, country-wide offset shifts). Its key differentiator among similar data packages is its focus on a specific geographical subset, leading to a smaller footprint for applications that only require North American time zone data, and its direct JSON format which is easy to parse.","status":"active","version":"1.0.48","language":"javascript","source_language":"en","source_url":"https://github.com/rogierschouten/tzdata-generate","tags":["javascript"],"install":[{"cmd":"npm install tzdata-northamerica","lang":"bash","label":"npm"},{"cmd":"yarn add tzdata-northamerica","lang":"bash","label":"yarn"},{"cmd":"pnpm add tzdata-northamerica","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const jsonData = require('tzdata-northamerica');","symbol":"jsonData","correct":"import jsonData from 'tzdata-northamerica';"},{"note":"For browser usage, including the UMD bundle script in your HTML creates a global variable `tzdataNorthamerica` which holds the time zone data.","symbol":"tzdataNorthamerica","correct":"<!-- In HTML: <script src=\"./node_modules/tzdata-northamerica/tzdata-northamerica.js\"></script> -->\n<script>\n    function onLoad() {\n        const data = tzdataNorthamerica;\n        console.log('Loaded North America TZ data in browser.');\n    }\n</script>"}],"quickstart":{"code":"import jsonData from 'tzdata-northamerica';\n\n// Access specific time zone data by IANA name\nconst newYorkData = jsonData['America/New_York'];\nconst losAngelesData = jsonData['America/Los_Angeles'];\n\nconsole.log('--- Time Zone Data for America/New_York ---');\nif (newYorkData) {\n  // The data structure is an object where keys might represent years or rule sets.\n  // This example just shows a simplified view of its content.\n  console.log(`America/New_York data is available. It has ${Object.keys(newYorkData).length} top-level entries.`);\n  const firstKey = Object.keys(newYorkData)[0];\n  if (firstKey) {\n    console.log(`First entry for America/New_York (key: ${firstKey}):`, newYorkData[firstKey]);\n  }\n} else {\n  console.log('Error: America/New_York data not found. This should not happen with tzdata-northamerica.');\n}\n\nconsole.log('\\n--- Time Zone Data for America/Los_Angeles ---');\nif (losAngelesData) {\n  console.log(`America/Los_Angeles data is available. It has ${Object.keys(losAngelesData).length} top-level entries.`);\n} else {\n  console.log('Error: America/Los_Angeles data not found. This should not happen with tzdata-northamerica.');\n}\n\n// Attempting to access a non-North American zone will result in undefined\nconst berlinData = jsonData['Europe/Berlin'];\nconsole.log('\\nAttempting to access Europe/Berlin (not in this package):', berlinData);\n// Expected output for Berlin: undefined\n\n// To use this data meaningfully, typically you'd pass it to a library like timezonecomplete.\n// Example (conceptual, requires timezonecomplete setup):\n// import { TzDatabase, DateTime } from 'timezonecomplete';\n// TzDatabase.init([jsonData]); // Initialize with the loaded data\n// const nowInNYC = new DateTime('now', 'America/New_York');\n// console.log('Current time in New York (conceptual):', nowInNYC.toString());","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'America/New_York') or similar `TypeError` when accessing a zone"},{"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.","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.","error":"tzdataNorthamerica is not defined"},{"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`).","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.","error":"Expected time zone 'Europe/Berlin' but got 'undefined' when accessing `jsonData['Europe/Berlin']`"}],"ecosystem":"npm"}