geo-tz

Install the package using npm to use geographical timezone lookups in your Node.js project.

npm install geo-tz

Because geo-tz reads data files from the data/ directory at runtime, standard bundlers may not include them automatically.

To fix this:

1. Explicitly copy the data/ directory to your bundle's output location.
2. Set the GEO_TZ_DATA_PATH environment variable to point to that directory so the library knows where to find the files.

By default, geo-tz lazy-loads lookup data into an unexpiring cache. Use setCache(options) to modify this behavior.

Options:

• preload (boolean): If true, attempts to cache all files at startup. This results in slower startup and higher memory usage.
• store (Map-like object): Allows offloading the cache to a custom storage solution. The object must be compatible with the Map API.

const { setCache } = require('geo-tz')

// Preload all files
setCache({ preload: true })

// Use a custom Map-like storage
let map = new Map();
setCache({ store: map })

The find(lat, lon) method returns an array of IANA timezone identifiers found at the specified latitude and longitude.

Note:

• If a coordinate is exactly on a border, multiple timezones may be returned.
• If the coordinate is at sea or in an uninhabited area, a timezone at sea (e.g., Etc/GMT*) will be returned.
• The default data product returns timezones that have been alike since 1970.

const { find } = require('geo-tz')

find(47.650499, -122.350070)  // ['America/Los_Angeles']
find(43.839319, 87.526148)  // ['Asia/Shanghai', 'Asia/Urumqi']

Use the find function to retrieve an array of timezone IDs (TZIDs) for a specific latitude and longitude, based on how timezones were defined in 1970.

Note: This method uses the official timezone database but may exclude certain 'deprecated' zones that had different timekeeping methods prior to 1970.

import { find } from 'node-geo-tz/find-1970';

// lat must be between -90 and 90
// lon must be between -180 and 180
const timezones = find(40.7128, -74.0060);
console.log(timezones); // e.g., ['America/New_York']

The setCache function allows you to configure how timezone data is cached to optimize lookup performance. It accepts a CacheOptions object.

You can also use the GEO_TZ_DATA_PATH environment variable to specify a custom path to the timezone data files. If not provided, it defaults to the data directory relative to the package installation.

import { setCache } from 'node-geo-tz/find-1970';

// Example: setting cache options
setCache({ preload: false });

Use find(lat, lon) to retrieve an array of all timezone IDs (TZIDs) that have ever existed at the specified GPS coordinates. This method is comprehensive and may include 'deprecated' zones that had different timekeeping methods prior to 1970.

Parameters:

• lat: Latitude (must be between -90 and 90).
• lon: Longitude (must be between -180 and 180).

Returns: An array of strings representing the timezone IDs.

import { find } from 'node-geo-tz';

const timezones = find(40.7128, -74.0060);
console.log(timezones); // e.g., ['America/New_York']

Call preCache() to load all timezone features into memory immediately. This increases initial memory consumption but significantly speeds up subsequent find() lookups.

import { preCache } from 'node-geo-tz';

// Call this during application startup
preCache();

Call preCache() to load all timezone features into memory. This is useful for applications that perform frequent lookups and want to avoid the overhead of reading from disk during runtime.

import { preCache, find } from 'node-geo-tz/find-1970';

// Load everything into memory first
preCache();

// Subsequent lookups will be faster
const tz = find(34.0522, -118.2437);

The getTimezoneAtSea function returns an array of Etc/GMT* timezone identifiers corresponding to a specific longitude. This is useful for determining timezones when coordinates fall in oceanic regions where standard land-based timezone boundaries may not apply.

Behavioral Notes:

• If the longitude is exactly -180 or 180, the function returns both ['Etc/GMT+12', 'Etc/GMT-12'].
• The function iterates through predefined oceanZones to find matching tzid values based on longitude boundaries.

import { getTimezoneAtSea } from 'geo-tz';

const tzs = getTimezoneAtSea(10.5);
// Returns an array of matching Etc/GMT identifiers