tz-geo

• We thank evansiroky, this library is compatible with his great work at node-geo-tz
• Made with Natural Earth. Data from www.naturalearthdata.com.

Features

• ✅ Universal: Works in both Node.js and browser environments
• ✅ TypeScript Support: Full type definitions included
• ✅ Moment.js Integration: Built on moment-timezone for robust date/time handling
• ✅ Self-Contained: Embedded GeoJSON data - no external file dependencies
• ✅ ES Modules: Modern import/export syntax

Install

npm install tz-geo

Quick Start

See example.md for browser usage examples.

Usage

Node.js

    var tzgeo = require('tz-geo')
    var name         = tzgeo.tz(47.650499, -122.350070)                                // 'America/Los_Angeles'
    var now          = tzgeo.tzMoment(47.650499, -122.350070)                          // moment-timezone obj
    var specificTime = tzgeo.tzMoment(47.650499, -122.350070, '2016-03-30T01:23:45Z')  // moment-timezone obj

    //Returns an error or timezone string via callback
    tzgeo.getTimezone({ type: 'Point', coordinates: [51.48513770164579, 5.232168700000033 ] }, function(err, result){
      if (err) throw err;
      console.log(result.name);
    });

    //Returns an error or moment-timezone via callback
    tzgeo.getMoment({ type: 'Point', coordinates: [51.48513770164579, 5.232168700000033 ] }, function(err, result){
      if (err) throw err;
      console.log(result.name);
    });

Browser with Bundler

Since the library is built as CommonJS for Node.js compatibility, use a bundler like Webpack, Rollup, or Vite for browser usage:

import { tz, tzMoment, getTimezone, getMoment } from 'tz-geo';

const name = tz(47.650499, -122.350070); // 'America/Los_Angeles'
const now = tzMoment(47.650499, -122.350070); // moment-timezone obj

// Async timezone lookup with merged MomentZone data
getTimezone({ type: 'Point', coordinates: [51.48513770164579, 5.232168700000033 ] }, (err, result) => {
  if (err) throw err;
  console.log(result.name);        // IANA timezone name
  console.log(result.abbrs);       // Array of abbreviations
  console.log(result.offsets);     // Array of offsets
  console.log(result.time_zone);   // UTC format like "UTC+02:00"
  console.log(result.abbr(1640995200000)); // Get abbreviation for timestamp
});

Note: The library includes embedded timezone data (~5.7MB), so it's completely self-contained and works without any external dependencies or network requests.

TypeScript

import { tz, tzMoment, getTimezone, Point } from 'tz-geo';

const coordinates: Point = { type: 'Point', coordinates: [-122.350070, 47.650499] };
const timezoneName: string = tz(47.650499, -122.350070);
const momentObj = tzMoment(47.650499, -122.350070, '2023-07-01T12:00:00Z');

API Docs:

.tz(lat, lon)

Returns timezone name found at lat, lon. Returns null if timezone could not be found at coordinate.

.tzMoment(lat, lon, [dateTime])

Returns a moment-timezone object found at lat, lon. Returns null if timezone could not be found at coordinate. If dateTime is omitted, the moment-timezone will have the current time set. If dateTime is provided, moment-timezone will be set to the time provided according to the timezone found. dateTime can be any single-argument parameter that will get passed to the moment() parser.

.getTimezone(point, callback)

Returns a timezone string found at {type: 'point', coordinates: [lon, lat]}. Returns err if timezone could not be found or no moment-timezone could be constructed from the geojson. If no moment-timezone can be constructed, please let us know so we can add it to our datafile.

.getMoment(point, callback)

Returns a moment-timezone object found at {type: 'point', coordinates: [lon, lat]}. Returns err if timezone could not be found or no moment-timezone could be constructed from the geojson. If no moment-timezone can be constructed, please let us know so wee can add it to our datafile.