tz-lookup

This package is optimized for speed and small bundle size, making it ideal for browser environments or high-throughput applications. However, it trades off accuracy due to the lossy compression required for its small footprint.

Comparison with geo-tz

Recommendation: If high accuracy is critical and you are running in a Node.js environment, use geo-tz instead.

To use this library in your project, install it using npm:

npm install @photostructure/tz-lookup

For browser-based usage, include the tz.js script and call the global tzlookup function.

<script src="tz.js"></script>
<script>
  alert(tzlookup(42.7235, -73.6931)); // alerts "America/New_York"
</script>

In a Node.js environment, require the module and call the exported function with latitude and longitude to get the IANA timezone string.

Note: The function will throw an error if the latitude or longitude provided are NaN or out of bounds. Otherwise, it always returns an IANA timezone database string.

var tzlookup = require("@photostructure/tz-lookup");
console.log(tzlookup(42.7235, -73.6931)); // prints "America/New_York"

The tzlookup(Y, W) function is the primary API for estimating a time zone based on geographic coordinates. It takes two parameters representing latitude and longitude and returns a string representing the estimated time zone.

Parameters:

• Y: Latitude (number)
• W: Longitude (number)

Returns:

• A string representing the estimated time zone (e.g., 'Europe/London').

// Example usage (assuming tzlookup is available in your scope)
const timeZone = tzlookup(51.5074, -0.1278);
console.log(timeZone); // e.g., 'Europe/London'

The tzlookup function estimates a time zone identifier (e.g., America/New_York) based on latitude and longitude coordinates.

Usage

Call tzlookup(latitude, longitude) with the following constraints:

• Latitude: Must be between -90 and 90 inclusive.
• Longitude: Must be between -180 and 180 inclusive.

Error Handling

If the provided coordinates are outside the valid ranges, the function throws a RangeError with the message "invalid coordinates".

Return Values

• Returns a string representing the time zone (e.g., "Africa/Cairo", "Europe/London").
• If the latitude is exactly 90 (North Pole), it returns "Etc/GMT".

const tzlookup = require('tz-lookup');

// Example: Estimate time zone for New York City
const lat = 40.7128;
const lon = -74.0060;
const timezone = tzlookup(lat, lon);
console.log(timezone); // "America/New_York"