A precise IANA timezone resolver and converter — desktop GUI, REST API, web server, and a static site that runs fully offline.
Live web version — tzc.ash1421.com
🌍 Timezone Resolver — Maps cities, states, countries, and abbreviations to correct IANA strings, with regional edge-case handling (e.g. western Kansas → Mountain Time, Florida panhandle → Central Time)
⏱ Time Converter — DST-aware conversion between any two IANA timezones
🖥️ Desktop GUI — Dark purple customtkinter app with live world clocks
🌐 Static Web Page — Works offline by cloning the repo and opening index.html; also live at tzc.ash1421.com
🔌 Flask REST API — Serve the app and API locally with --server
💻 CLI — Resolve or convert directly from your terminal
The static site lives in the root of this repo (index.html + assets/). It is automatically deployed to tzc.ash1421.com on every push to main.
It works fully offline too — clone the repo and open index.html directly in your browser. No server or build step needed.
# 1. Clone the repo
git clone https://github.com/Ash1421/TZ-Convert.git
cd TZ-Convert
# 2. Install dependencies
# tzdata is required on Windows — it provides the timezone database
pip install -r requirements.txt
# 3. Launch (GUI by default)
python src/main.pypython src/main.py
python src/main.py --guiThree tabs: Converter, Resolver, and World Clocks. World Clocks updates live every second.
python src/main.py --server
# Open http://127.0.0.1:5000
# Custom host and port:
python src/main.py --server --host 0.0.0.0 --port 8080Serves the same static frontend as the GitHub Pages site, plus the REST API at /api/.
# Resolve a location to its IANA timezone
python src/main.py --cli Denver
python src/main.py --cli "Goodland, KS"
python src/main.py --cli PST
python src/main.py --cli Australia
python src/main.py --cli "New Zealand"
# Convert a time between zones
python src/main.py --cli "2026-06-22 14:30" UTC "Australia/Sydney"
python src/main.py --cli "2026-06-22 09:00" "America/Denver" "Asia/Tokyo"REST API Reference
All endpoints return JSON. Default base: http://127.0.0.1:5000
GET /api/convert — Convert a time
| Parameter | Required | Description |
|---|---|---|
time |
yes | YYYY-MM-DD HH:MM |
from |
yes | Source IANA timezone (or alias / location) |
to |
yes | Target IANA timezone (or alias / location) |
/api/convert?time=2026-06-22+14:30&from=UTC&to=Australia/Sydney
GET /api/resolve — Resolve a location
/api/resolve?location=Denver
/api/resolve?location=Goodland%2C+KS
/api/resolve?location=Australia
GET /api/current — Current time in a timezone
/api/current?tz=America/Denver
GET /api/timezones — Search IANA strings
/api/timezones?q=australia
/api/timezones?prefix=America
GET /api/world — World clock snapshot
Resolution Logic
The resolver works through 10 priority steps:
- Timezone alias —
PST→America/Los_Angeles - Direct IANA string —
America/Denverpassed through validated - City lookup —
Denver→America/Denver - City + region —
Goodland, KS→America/Denver(western Kansas override) - US state —
Kansas→America/Chicago - Country —
Australia→Australia/Sydney - Fuzzy city match
- Fuzzy state match
- Fuzzy country match
- System timezone fallback
Multi-timezone state overrides:
| State | Default | Override |
|---|---|---|
| Kansas | America/Chicago |
Western counties (Goodland, Liberal, Garden City…) → America/Denver |
| Florida | America/New_York |
Panhandle (Pensacola, Destin…) → America/Chicago |
| Texas | America/Chicago |
Far west (El Paso, Marfa…) → America/Denver |
Building the EXE
Requires Windows (or the Windows runner in CI).
pip install pyinstaller tzdata
pip install -r requirements.txt
pyinstaller tz_convert.spec --noconfirm
# Output: dist/tz-convert.exeThis project is licensed under the GPL V3.0 (GNU General Public License V3.0).
Made with 💜 by @Ash1421
⭐ Star this repo if it helped! ⭐
