{"id":2345,"library":"tzfpy","title":"tzfpy","description":"tzfpy is a high-performance Python package for converting longitude and latitude coordinates to timezone names. Rewritten in Rust (using PyO3), it aims for speed over absolute precision, leveraging simplified polygon data. The current version is 1.1.3, and it maintains an active release cadence with frequent updates.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/ringsaturn/tzfpy","tags":["timezone","geolocation","latitude-longitude","performance","rust","pyo3","geospatial"],"install":[{"cmd":"pip install tzfpy","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"tzfpy[tzdata]\"","lang":"bash","label":"Recommended Installation (with tzdata extra)"}],"dependencies":[{"reason":"Required Python version.","package":"python","version":">=3.10","optional":false},{"reason":"Recommended for best practices when handling timezone objects with Python's built-in `zoneinfo` module.","package":"tzdata","optional":true},{"reason":"Optional dependency for compatibility with older timezone handling libraries, though `tzdata` with `zoneinfo` is generally preferred.","package":"pytz","optional":true}],"imports":[{"note":"Primary function to get a single timezone name for coordinates.","symbol":"get_tz","correct":"from tzfpy import get_tz"},{"note":"Function to get all possible timezone names for coordinates, useful near borders.","symbol":"get_tzs","correct":"from tzfpy import get_tzs"},{"note":"For data visualization, retrieves GeoJSON polygon data for a given timezone.","symbol":"get_tz_polygon_geojson","correct":"from tzfpy import get_tz_polygon_geojson"},{"note":"For data visualization, retrieves GeoJSON index data for a given timezone.","symbol":"get_tz_index_geojson","correct":"from tzfpy import get_tz_index_geojson"}],"quickstart":{"code":"from datetime import datetime, timezone\nfrom zoneinfo import ZoneInfo\nfrom tzfpy import get_tz\n\n# Example coordinates for Tokyo, Japan\nlongitude = 139.7744\nlatitude = 35.6812\n\n# Get the timezone name from coordinates\ntz_name = get_tz(longitude, latitude)\nprint(f\"Timezone for ({longitude}, {latitude}): {tz_name}\")\n\n# Use the timezone name with Python's built-in zoneinfo for datetime objects\nif tz_name:\n    try:\n        tokyo_tz = ZoneInfo(tz_name)\n        now_utc = datetime.now(timezone.utc)\n        now_local = now_utc.replace(tzinfo=tokyo_tz)\n        print(f\"Current UTC time: {now_utc}\")\n        print(f\"Current local time in {tz_name}: {now_local}\")\n    except Exception as e:\n        print(f\"Error creating ZoneInfo object for '{tz_name}': {e}\")\nelse:\n    print(f\"Could not determine timezone for ({longitude}, {latitude})\")\n","lang":"python","description":"This quickstart demonstrates how to retrieve a timezone name for given coordinates using `tzfpy.get_tz` and then apply it to a `datetime` object using Python's standard `zoneinfo` module. It is recommended to install `tzfpy` with the `tzdata` extra for optimal `zoneinfo` compatibility."},"warnings":[{"fix":"Be aware of this trade-off. For higher precision, consider `timezonefinder`. For general use, `tzfpy` provides excellent performance.","message":"tzfpy uses simplified polygon data for speed, which means its accuracy may be reduced, especially around timezone borders. For applications requiring extremely high precision near boundaries, alternatives like `timezonefinder` might be more suitable, though potentially slower.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If latency on the very first call is critical, consider making a dummy call during application startup to pre-load the data (e.g., `get_tz(0, 0)`).","message":"The underlying Rust implementation uses lazy initialization. This means the very first call to `get_tz` or `get_tzs` will be slower than subsequent calls as the data structures are loaded into memory.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Factor the 40MB memory footprint into your application's resource planning.","message":"The library utilizes approximately 40MB of memory for its internal data structures. While efficient for its task, this should be considered in memory-constrained environments.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `tzfpy` using `pip install \"tzfpy[tzdata]\"` and utilize `from zoneinfo import ZoneInfo` for robust timezone handling.","message":"New timezone names added to `tzfpy` might be incompatible with older versions of timezone packages like `pytz` or system `tzdata`. The recommended approach is to install `tzfpy` with the `[tzdata]` extra and use Python's built-in `zoneinfo` module.","severity":"gotcha","affected_versions":"All versions, especially when mixing with older timezone libraries"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}