{"id":22339683,"url":"https://github.com/ringsaturn/tzfpy","last_synced_at":"2026-03-14T11:01:08.036Z","repository":{"id":63897105,"uuid":"568766261","full_name":"ringsaturn/tzfpy","owner":"ringsaturn","description":"Probably the fastest Python package to convert longitude/latitude to timezone name.","archived":false,"fork":false,"pushed_at":"2026-03-01T09:28:15.000Z","size":744,"stargazers_count":133,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T13:13:06.386Z","etag":null,"topics":["gps-location","latitude","longitude","python","python-library","rust","timezone","timezone-library","timezone-picker","tzf"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/tzfpy/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ringsaturn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"polar":null,"custom":["https://redcross.org.ua/en/donate/"]}},"created_at":"2022-11-21T11:14:13.000Z","updated_at":"2026-03-01T09:28:18.000Z","dependencies_parsed_at":"2023-11-25T18:30:20.977Z","dependency_job_id":"ce09b730-55c6-49fe-bfa3-b3e418e97473","html_url":"https://github.com/ringsaturn/tzfpy","commit_stats":{"total_commits":30,"total_committers":3,"mean_commits":10.0,"dds":"0.16666666666666663","last_synced_commit":"00a70bed2e62513a81a0ab20e0294a314a284595"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/ringsaturn/tzfpy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Ftzfpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Ftzfpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Ftzfpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Ftzfpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ringsaturn","download_url":"https://codeload.github.com/ringsaturn/tzfpy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Ftzfpy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30383554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gps-location","latitude","longitude","python","python-library","rust","timezone","timezone-library","timezone-picker","tzf"],"created_at":"2024-12-04T07:09:07.217Z","updated_at":"2026-03-11T14:17:14.433Z","avatar_url":"https://github.com/ringsaturn.png","language":"Python","funding_links":["https://redcross.org.ua/en/donate/"],"categories":["Geospatial"],"sub_categories":[],"readme":"# tzfpy\n\n- [![PyPI](https://img.shields.io/pypi/v/tzfpy)](https://pypi.org/project/tzfpy/)\n- [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tzfpy)](https://pypi.org/project/tzfpy/)\n- ![PyPI - Downloads](https://img.shields.io/pypi/dd/tzfpy)\n- [![Anaconda-Server Badge](https://anaconda.org/conda-forge/tzfpy/badges/version.svg)](https://anaconda.org/conda-forge/tzfpy)\n- ![Conda Downloads](https://img.shields.io/conda/d/conda-forge/tzfpy)\n- ![Conda Platform](https://img.shields.io/conda/p/conda-forge/tzfpy)\n\n![](https://github.com/ringsaturn/tzf/blob/gh-pages/docs/tzf-social-media.png?raw=true)\n\n\u003e [!NOTE]\n\u003e\n\u003e 0. It's probably the fastest Python package to convert longitude/latitude to\n\u003e    timezone name.\n\u003e 1. This package use a simplified polygon data and not so accurate around\n\u003e    borders.\n\u003e 2. Rust use lazy init, so first calling will be a little slow.\n\u003e 3. Use about 40MB memory.\n\u003e 4. It's tested under Python 3.10+.\n\u003e 5. Try it online:\n\u003e    - \u003chttps://ringsaturn.github.io/tzf-web/\u003e, powered by tzf-rs and\n\u003e      WebAssembly\n\n## Usage\n\nPlease note that new timezone names may be added to tzfpy, which could be\nincompatible with old version package like pytz or tzdata. As an option, tzfpy\nsupports install compatible version of those packages with extra params.\n\n```bash\n# Install just tzfpy\npip install tzfpy\n\n# Install with pytz\npip install \"tzfpy[pytz]\"\n\n# Install with tzdata. https://github.com/python/tzdata\npip install \"tzfpy[tzdata]\"\n\n# Install via conda, see more in https://github.com/conda-forge/tzfpy-feedstock\nconda install -c conda-forge tzfpy\n```\n\n```python\n\u003e\u003e\u003e from tzfpy import get_tz, get_tzs\n\u003e\u003e\u003e get_tz(116.3883, 39.9289)  # in (longitude, latitude) order.\n'Asia/Shanghai'\n\u003e\u003e\u003e get_tzs(87.4160, 44.0400)  # in (longitude, latitude) order.\n['Asia/Shanghai', 'Asia/Urumqi']\n```\n\nFor data visualization, you can get timezone polygon GeoJSON data from tzfpy:\n\n```python\nfrom tzfpy import get_tz, get_tz_index_geojson, get_tz_polygon_geojson\n\nlng = -74.0060\nlat = 40.7128\ntz = get_tz(lng, lat)\nprint(f\"Timezone for ({lng}, {lat}): {tz}\")\n\nwith open(\"tz_nyc_polygon.geojson\", \"w\") as f:\n    geojson_data = get_tz_polygon_geojson(tz)\n    f.write(geojson_data)\n\nwith open(\"tz_nyc_index.geojson\", \"w\") as f:\n    geojson_data = get_tz_index_geojson(tz)\n    f.write(geojson_data)\n```\n\n### Best practices\n\n1. Always install tzfpy with `tzdata` extra: `pip install tzfpy[tzdata]`\n2. Use Python's zoneinfo package(`import zoneinfo`, aka\n   [`tzdata` in PyPI](https://pypi.org/project/tzdata/)) to handle timezone\n   names, even if you are using arrow:\n\n   [`examples/tzfpy_with_datetime.py`](examples/tzfpy_with_datetime.py):\n\n   ```python\n   from datetime import datetime, timezone\n   from zoneinfo import ZoneInfo\n\n   from tzfpy import get_tz\n\n   tz = get_tz(139.7744, 35.6812)  # Tokyo\n\n   now = datetime.now(timezone.utc)\n   now = now.replace(tzinfo=ZoneInfo(tz))\n   print(now)\n   # 2025-04-29 01:33:56.325194+09:00\n   ```\n\n   [`examples/tzfpy_with_arrow.py`](examples/tzfpy_with_arrow.py):\n\n   ```python\n   from zoneinfo import ZoneInfo\n\n   import arrow\n   from tzfpy import get_tz\n\n   tz = get_tz(139.7744, 35.6812)  # Tokyo\n\n   arrow_now = arrow.now(ZoneInfo(tz))\n   print(arrow_now.format(\"YYYY-MM-DD HH:mm:ss ZZZ\"))\n   # 2025-04-29 01:33:56.325194+09:00\n   ```\n\n   If you are using whenever, since whenever use tzdata internally, so it's\n   compatible with tzfpy:\n\n   [`examples/tzfpy_with_whenever.py`](examples/tzfpy_with_whenever.py):\n\n   ```python\n   from whenever import Instant\n   from tzfpy import get_tz\n\n   now = Instant.now()\n\n   tz = get_tz(139.7744, 35.6812)  # Tokyo\n\n   now = now.to_tz(tz)\n\n   print(now)\n   # 2025-04-29T10:33:28.427784+09:00[Asia/Tokyo]\n   ```\n\n## Performance\n\nBenchmark runs under\n[`v1.0.0`](https://github.com/ringsaturn/tzfpy/releases/tag/v1.0.0) on my\nMacBook Pro with Apple M3 Max.\n\n```bash\npytest --benchmark-warmup=on --benchmark-warmup-iterations=100 tests/test_bench.py\n```\n\n```\n-------------------------------------------------------------- benchmark: 1 tests --------------------------------------------------------------\nName (time in ns)                 Min          Max        Mean      StdDev      Median         IQR    Outliers  OPS (Kops/s)  Rounds  Iterations\n------------------------------------------------------------------------------------------------------------------------------------------------\ntest_tzfpy_random_cities     895.7926  11,420.8087  2,597.6093  1,331.8472  2,337.5032  1,587.5907  11611;1000      384.9694   33614          10\n------------------------------------------------------------------------------------------------------------------------------------------------\n\nLegend:\n  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.\n  OPS: Operations Per Second, computed as 1 / Mean\nResults (2.03s):\n         1 passed\n```\n\nOr you can view more benchmark results on\n[GitHub Action summary page](https://github.com/ringsaturn/tzfpy/actions/workflows/Test.yml).\n\nMore benchmarks compared with other packages can be found in\n[ringsaturn/tz-benchmark](https://github.com/ringsaturn/tz-benchmark).\n\n## Background\n\n`tzfpy` was originally written in Go named [`tzf`][tzf] and use CGO compiled to\n`.so` to be used by Python. Since `v0.11.0` it's rewritten in Rust built on PyO3\nand [`tzf-rs`][tzf-rs], a tzf's Rust port.\n\nI have written an article about the history of tzf, its Rust port, and its Rust\nport's Python binding; you can view it\n[here](https://blog.ringsaturn.me/en/posts/2023-01-31-history-of-tzf/).\n\n[tzf]: https://github.com/ringsaturn/tzf\n[tzf-rs]: https://github.com/ringsaturn/tzf-rs\n\n## Compare with other packages\n\nPlease note that directly compare with other packages is not fair, because they\nhave different use cases and design goals, for example, the precise.\n\n### [TimezoneFinder](https://github.com/jannikmi/timezonefinder)\n\nI got lots of inspiration from it. Timezonefinder is a very good package and\nit's mostly written in Python, so it's easy to use. And it's much\n[more widely used](https://github.com/jannikmi/timezonefinder/network/dependents)\ncompared with tzfpy if you care about that.\n\nHowever, it's slower than tzfpy, especially around the borders, and I have lots\nof API requests from there. That's the reason I created tzf originally. And then\ntzf-rs and tzfpy.\n\n### [pytzwhere](https://github.com/pegler/pytzwhere)\n\nI recommend to read timezonefinder's\n[Comparison to pytzwhere](https://timezonefinder.readthedocs.io/en/latest/3_about.html#comparison-to-pytzwhere)\nsince it's very detailed.\n\n## Contributing\n\nInstall:\n\n- [Rust](https://www.rust-lang.org/tools/install)\n- [Python](https://www.python.org/downloads/)\n- [uv](https://docs.astral.sh/uv/)\n\n```console\nAvailable commands:\n  build    - Build the project using uv\n  fmt      - Format the code using ruff\n  lint     - Lint the code using ruff\n  sync     - Sync and compile the project using uv\n  lock     - Lock dependencies using uv\n  upgrade  - Upgrade dependencies using uv\n  all      - Run lock, sync, fmt, lint, and test\n  test     - Run tests using pytest\n```\n\n```bash\nmake all\n```\n\n## LICENSE\n\nThis project is licensed under the [MIT license](./LICENSE) and\n[Anti CSDN License](./LICENSE_ANTI_CSDN.md)[^anti_csdn]. The data is licensed\nunder the\n[ODbL license](https://github.com/ringsaturn/tzf-rel/blob/main/LICENSE), same as\n[`evansiroky/timezone-boundary-builder`](https://github.com/evansiroky/timezone-boundary-builder)\n\n[^anti_csdn]: This license is to prevent the use of this project by CSDN, has no\n    effect on other use cases.\n\n\u003c!-- ## Other info\n\n[![](https://ringsaturn.github.io/pypi-downloads-chart/tzfpy/download-trends.svg)](https://ringsaturn.github.io/pypi-downloads-chart/tzfpy/index.html) --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringsaturn%2Ftzfpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringsaturn%2Ftzfpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringsaturn%2Ftzfpy/lists"}