{"id":1882,"library":"timezonefinder","title":"Timezone Finder","description":"timezonefinder is a Python package for efficiently determining the timezone of any geographic point on Earth (given its coordinates) entirely offline. It uses a custom database of timezone polygons. The current stable version is 8.2.2. The library is actively maintained, with significant updates and breaking changes occurring with major version releases, such as v8.0.0 in early 2024.","status":"active","version":"8.2.2","language":"en","source_language":"en","source_url":"https://github.com/MrMinimal64/timezonefinder","tags":["timezone","location","geospatial","offline","coordinates"],"install":[{"cmd":"pip install timezonefinder","lang":"bash","label":"Install stable version"},{"cmd":"pip install timezonefinder[full]","lang":"bash","label":"Install with scipy for faster results"}],"dependencies":[{"reason":"Optional dependency. Installing 'scipy' (via `pip install timezonefinder[full]`) enables a faster timezone lookup algorithm ('L' version) which `TimezoneFinder` automatically utilizes.","package":"scipy","optional":true}],"imports":[{"note":"As of v8.0.0, `TimezoneFinderL` has been removed. The standard `TimezoneFinder` class will automatically use the faster, 'L' algorithm if 'scipy' is installed.","wrong":"from timezonefinder import TimezoneFinderL","symbol":"TimezoneFinder","correct":"from timezonefinder import TimezoneFinder"}],"quickstart":{"code":"from timezonefinder import TimezoneFinder\n\ntf = TimezoneFinder()\n\n# Example coordinates: Berlin, Germany\nlongitude = 13.4050\nlatitude = 52.5200\n\n# Find the timezone at the given coordinates\ntimezone_str = tf.timezone_at(lng=longitude, lat=latitude)\n\nprint(f\"The timezone at ({latitude}, {longitude}) is: {timezone_str}\")\n\n# Example where no timezone is found (e.g., open ocean)\nlongitude_ocean = 0.0\nlatitude_ocean = 0.0\nempty_timezone_str = tf.timezone_at(lng=longitude_ocean, lat=latitude_ocean)\n\nprint(f\"The timezone at ({latitude_ocean}, {longitude_ocean}) is: {empty_timezone_str}\")","lang":"python","description":"This quickstart demonstrates how to initialize `TimezoneFinder` and use `timezone_at` to find the timezone for specific geographic coordinates. It highlights the use of named arguments for longitude and latitude to avoid common coordinate order mistakes."},"warnings":[{"fix":"Change `from timezonefinder import TimezoneFinderL` to `from timezonefinder import TimezoneFinder`. Ensure 'scipy' is installed (`pip install timezonefinder[full]`) if the faster algorithm is desired.","message":"The separate `TimezoneFinderL` class (accessed via `from timezonefinder import TimezoneFinderL`) has been removed. Users should now always import `TimezoneFinder`. If `scipy` is installed, `TimezoneFinder` will automatically use the faster 'L' algorithm.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Remove the `force_reload` parameter from your `TimezoneFinder` initialization calls. The library manages data loading automatically.","message":"The `force_reload` parameter in the `TimezoneFinder` constructor (`__init__`) has been removed. Data reloading is now handled internally and not exposed via this parameter.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"If you were using `in_memory`, rename the parameter to `in_memory_threshold` in your `TimezoneFinder` initialization. For example, `TimezoneFinder(in_memory=True)` becomes `TimezoneFinder(in_memory_threshold=1)`.","message":"The `in_memory` parameter in the `TimezoneFinder` constructor (`__init__`) has been renamed to `in_memory_threshold`.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Always use named arguments `lng=` and `lat=` (e.g., `tf.timezone_at(lng=10.0, lat=50.0)`) to ensure correct coordinate order and improve code readability.","message":"Coordinate order is consistently `(longitude, latitude)` or `(lng, lat)`. It's a common mistake to swap these, especially with other geospatial libraries. The `timezone_at` method specifically uses `lng=` and `lat=` named arguments.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Initialize `TimezoneFinder()` once and reuse the instance throughout your application's lifecycle. Avoid initializing it repeatedly within loops or request handlers.","message":"The `TimezoneFinder` object loads its ~100MB data file into memory upon initialization. This can cause a noticeable delay (several seconds) on first startup and consume significant RAM. Subsequent lookups are very fast.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}