wheretz

KO | EN

gitlite — search

#hacktoberfest #react #ai #golang #android #deep-learning #linux #nodejs #cli #vue #security #mcp #openai #open-source

(★ 102)

Fast and precise time zone by geo coordinates lookup

wheretz Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

WhereTZ: fast and precise timezone lookup
=========================================

**WhereTZ** is a small gem for lookup of timezone by georgraphic
coordinates.

Features:

* quite precise: uses [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder), which takes source data from OpenStreetMap;
* (relatively) fast: 0.1-0.2 sec for lookup in worst cases and almost immediate lookup for best cases;
* no calls to external services, works without Internet connection;
* no keeping some 50 Mb datafiles in memory or reading them from disk for each call;
* can return timezone name string or `TZInfo::Timezone`.

## Usage

Install it with your usual routines (Gemfile or `gem install`) as `wheretz` gem. Then:

```ruby
require 'wheretz'

WhereTZ.lookup(50.004444, 36.231389) # (lat, lng) order
# => 'Europe/Kiev'

WhereTZ.get(50.004444, 36.231389)
# => #<TZInfo::DataTimezone: Europe/Kiev>

# you should have tzinfo gem installed, wheretz doesn't list it as dependency
```

From command-line, after gem installed:

```bash
wheretz 50.004444,36.231389
# => Europe/Kiev
```

## How it works

1. Latest version of [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder) dataset is converted into ~400 `data/*.geojson` files;
2. Each of those files corresponds to one timezone; filename contains timezone name and _bounding box_ (min and max latitude and longitude);
3. On each lookup `WhereTZ` first checks provided coordinates by bounding boxes, and if only one bbox (extracted from filename) corresponds to them, returns timezone name immediately;
4. If there's several intersecting bounding boxes, `WhereTZ` reads only relevant timezone files (which are not very large) and checks which polygon actually contains the point.

## Known problems

* Loading/unloading `.geojson` files can be uneffective when called  multiple times; future releases will provide option for preserve data in memory, or for mass lookup of points;
* You should note that gem has ≈50 MiB of datafiles inside;
* Data conversion performed by pretty ugly script (instead of Rake task as it should be).

## Author

[Victor Shepelev](http://zverok.github.io/)

## License

Data license is [ODbL](https://opendatacommons.org/licenses/odbl/).

Code license is usual MIT.

wheretz

wheretz Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

wheretz

wheretz Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README