Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
The most up-to-date and accurate node.js geographical timezone lookup package. It's fast too!
npm install geo-tz
const { find } = require('geo-tz')
find(47.650499, -122.350070) // ['America/Los_Angeles']
find(43.839319, 87.526148) // ['Asia/Shanghai', 'Asia/Urumqi']
This library aims to do one thing and do it well: find the timezone(s) in use at a GPS coordinate. The output consists of timezone identifiers as defined in the timezone database. The underlying geographic data is obtained from the timezone-boudary-builder project. The data is indexed for fast analysis by caching subregions of geographic data when a precise lookup is needed.
This library does an exact geographic lookup which has tradeoffs. The results are more accurate than other libraries that compromise by approximating the lookup of the data. However, it is perhaps a little bit slower that other libraries, has a larger installation size on disk and may encounter difficulties when bundling.
As of version 8, node-geo-tz offers the ability to choose from the three different timezone boundary products that the timezone-boudary-builder project produces.
The default data product used by this library are unioned timezones that are alike since 1970. This is a breaking change from versions below version 8 that used timezone identifiers that generally had a minimum of one timezone per country. In a number of places, the timezone identifier returned will be that which has the highest population among all timezone identifiers with similar timekeeping methods since 1970.
const { find } = require('geo-tz')
find(12.826174, 45.036933) // ['Asia/Riyadh']
When using this product, it is possible that the timezone identifier returned will not be appropriate for calculating the observed time at the GPS coordinate prior to the year 1970.
A comprehensive dataset is available to query for all timezone identifiers available. This has the same behavior of this library prior to version 8. This version has the largest file size to accomodate all the needed boundaries. In this dataset, with a few rare exceptions, there is at least one unique timezone identifier per country.
const { find } = require('geo-tz/all')
find(12.826174, 45.036933) // ['Asia/Aden']
When using this product, the timezone identifier returned will be appropriate for calculating the observed time at the GPS coordinate including years prior to 1970.
A dataset containing a unioned set of timezones that share the same timekeeping method into the future is the final data product available. This version has the smallest file size as it does not include as many timezones and boundaries. In a number of places, the timezone identifier returned will be that which has the highest population among all timezone identifiers with similar timekeeping methods since the current time.
const { find } = require('geo-tz/now')
find(12.826174, 45.036933) // ['Europe/Moscow']
When using this product, the timezone identifier returned will only be appropriate for calculating the observed time at the GPS coordinate for the current and future time.
The API available is the same for each data product.
Returns the timezone identifiers found at lat
, lon
. There are certain coordinates where the timekeeping method will depend on the person you ask. Also, another case where 2 or more timezones could be returned is when a request is made with a coordinate that happens to be exactly on the border between two or more timezones. If the GPS coordinate does not fall inside any timezone boundary on land, then a timezone at sea will be returned.
const { find } = require('geo-tz')
find(47.650499, -122.350070) // ['America/Los_Angeles']
find(43.839319, 87.526148) // ['Asia/Shanghai', 'Asia/Urumqi']
By default, geoTz lazy-loads exact lookup data into an unexpiring cache. The setCache
method can be used to change the caching behavior using the following options:
preload
- if set to true will attempt to cache all files (slow startup time and requires lots of memory)store
- offload the cache to a custom storage solution (must be compatible with the Map api)Examples:
setCache({ preload: true }) // preloads all files
let map = new Map();
setCache({ store: map }) // pass a Map-like storage object
This library relies on reading a large data file from disk to perform exact geographic lookups. Therefore, it is not intended to be used in the browser and may have issues with bundlers if they don't include the necessary file.
The underlying data is obtained from the timezone-boudary-builder project. The data from that project is mostly sourced from OpenStreetMap which is editable by anyone. In most cases, the timezone boundaries follow officially observed boundaries, but often times some communities near timezone boundaries may follow whichever timekeeping method works best for them.
The boundaries in the ocean come from the timezone-boudary-builder project which only includes territorial waters and not exclusive economic zones. Additionally, special cases where the GPS coordinate falls with an area of Terra nullius will also have an ocean zone(s) returned.
The resulting timezone identifiers will represent the timekeeping method as is cataloged to the best of the knowledge of the maintainers of the timezone database. This could be wrong in the past (especially prior to 1970) and could change in the future should an area change the way they keep track of time.
Any concerns about the correctness of results are encouraged to be submitted as issues using the Incorrect Result Issue Template.
Due to the ever-changing nature of timezone data, it is critical that the latest version of this package is used. If older versions are used, there will be a few edge cases where the calculated time is wrong.
FAQs
A node.js module to find the timezone at specific gps coordinates
The npm package geo-tz receives a total of 85,693 weekly downloads. As such, geo-tz popularity was classified as popular.
We found that geo-tz demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.