timezonefinderL 4.0.2

lightweight python package for finding the timezone of any point on earth (coordinates)

timezonefinderL is the faster and lightweight, but inaccurate version of the original timezonefinder. Use this package in favour of timezonefinder when memory usage and speed matter more to you than accuracy.

Only the function timezone_at() is being supported and numba cannot be used for precompilation. The commands need to modified:

pip install timezonefinderL

from timezonefinderL import TimezoneFinder

tf = TimezoneFinder()

longitude, latitude = 13.358, 52.5061
tf.timezone_at(lng=longitude, lat=latitude)  # returns 'Europe/Berlin'

For everything else please refer to the original Documentation.

Operating Principle

Instead of storing timezone polygons and checking which polygon a query point is included in, like with the vanilla timezonefinder, this package uses only the precomputed shortcuts to instantly lookup a timezone. The zone which has the highest amount of timezone polygons (not covered surface!) in a shortcut is instantly being returned.

This requires far less memory and computing time, but of course is not accurate close to the borders of two neighbouring timezones.

The size of the shortcuts (<-> accuracy) is equal to the one used in the vanilla timezonefinder (1 shortcut per degree longitude, 2 per degree latitude, 260KB binary file size). In order to increase the accuracy (more and smaller shortcut rectangles), increment the parameters NR_SHORTCUTS_PER_LNG and NR_SHORTCUTS_PER_LAT in global_settings.py and compile a new binary shortcut file by running file_converter.py.

Speed Test Results:

obtained on MacBook Pro (15-inch, 2017), 2,8 GHz Intel Core i7 It can be seen that timezonefinderL is roughly one order of magnitude faster than timezonefinder:

Speed Tests:
-------------
"realistic points": points included in a timezone

in memory mode: False

testing 100000 realistic points
total time: 0.5513s
avg. points per second: 1.8 * 10^5

testing 100000 random points
total time: 0.5682s
avg. points per second: 1.8 * 10^5


in memory mode: True

testing 100000 realistic points
total time: 0.1688s
avg. points per second: 5.9 * 10^5


testing 100000 random points
total time: 0.1837s
avg. points per second: 5.4 * 10^5

Contact

Most certainly there is stuff I missed, things I could have optimized even further etc. I would be really glad to get some feedback on my code.

If you notice that the tz data is outdated, encounter any bugs, have suggestions, criticism, etc. feel free to open an Issue, add a Pull Requests on Git or …

contact me: [python] {-at-} [michelfe] {-*dot-} [it]*

License

timezonefinder is distributed under the terms of the MIT license (see LICENSE.txt).

Also see: GitHub, PyPI, GUI and API of the outdated timezonefinderL timezonefinder,

Changelog

4.0.2 (2019-05-23)

• MAJOR UPDATE: only the function timezone_at() is being supported

• not based on the simplification of the timezone polygons any more (not easily achievable with the new boundary data set)

• use the precomputed shortcuts to instantly look up a timezone (“instant shortcut”, most common zone of the polygons within that shortcut)

• updated the code to the status of the current timezonefinder main package v4.0.2

• data in use now is timezone-boundary-builder 2019a

• described options for increasing the accuracy in readme

• dropped python2 support

2.0.1 (2017-04-08)

• added missing package data entries (2.0.0 didn’t include all necessary .bin files)

2.0.0 (2017-04-07)

• introduction of this version of timezonefinder

• data has been simplified which affects speed and data size. Around 56% of the coordinates of the timezone polygons have been deleted and around 60% of the polygons (mostly small islands) have been included in the simplified polygons. For any coordinate on landmass the results should stay the same, but accuracy at the shorelines is lost. This eradicates the usefulness of closest_timezone_at() and certain_timezone_at() but the main use case for this package (= determining the timezone of a point on landmass) is improved.

• file_converter.py has been complemented and modified to perform those simplifications

• introduction of new function get_geometry() for querying timezones for their geometric shape

• added shortcuts_unique_id.bin for instantly returning an id if the shortcut corresponding to the coords only contains polygons of one zone

• data is now stored in separate binaries for ease of debugging and readability

• polygons are stored sorted after their timezone id and size

• timezonefinder can now be called directly as a script (experimental with reduced functionality, see readme)

• optimisations on point in polygon algorithm

• small simplifications in the helper functions

• clarification of the readme

• clarification of the comments in the code

• referenced the new conda-feedstock in the readme

• referenced the new timezonefinder API/GUI

for older versions refer to timezonefinder.