Timezones¶

3 endpoints for timezone conversion, coordinate-based lookup, and timezone metadata.

Python SDK Examples¶

Convert a timestamp between timezones¶

timezone_convert takes an ISO 8601 timestamp and converts it from one IANA timezone to another, returning both localised times and the hour difference.

from toolkitapi import Geo

with Geo(api_key="tk_...") as geo:
    result = geo.timezone_convert(
        "2026-06-01T09:00:00",
        from_tz="America/New_York",
        to_tz="Europe/London",
    )

    print(result["from_time"])          # "2026-06-01T09:00:00-04:00"
    print(result["to_time"])            # "2026-06-01T14:00:00+01:00"
    print(result["offset_diff_hours"])  # 5.0
    print(result["from_timezone"])      # "America/New_York"
    print(result["to_timezone"])        # "Europe/London"

Schedule a meeting across timezones¶

from toolkitapi import Geo

# Meeting at 10:00 AM London time — what's the equivalent for other offices?
meeting_time = "2026-09-15T10:00:00"
source_tz = "Europe/London"
office_timezones = {
    "New York":  "America/New_York",
    "São Paulo": "America/Sao_Paulo",
    "Dubai":     "Asia/Dubai",
    "Singapore": "Asia/Singapore",
    "Tokyo":     "Asia/Tokyo",
}

with Geo(api_key="tk_...") as geo:
    print(f"Meeting: {meeting_time} {source_tz}\n")
    for office, tz in office_timezones.items():
        result = geo.timezone_convert(meeting_time, from_tz=source_tz, to_tz=tz)
        # Extract just the time portion from the ISO string
        local_time = result["to_time"][11:16]
        offset = result["offset_diff_hours"]
        sign = "+" if offset >= 0 else ""
        print(f"  {office:12} → {local_time}  ({sign}{offset:g}h)")

Output:

Meeting: 2026-09-15T10:00:00 Europe/London

  New York     → 05:00  (-5h)
  São Paulo    → 06:00  (-4h)
  Dubai        → 13:00  (+3h)
  Singapore    → 17:00  (+7h)
  Tokyo        → 18:00  (+8h)

Resolve timezone from coordinates¶

timezone_by_coords is useful when you have a latitude/longitude (e.g. from a device's GPS or an IP lookup) and need the correct IANA timezone name.

from toolkitapi import Geo

coordinates = [
    ("Sydney Opera House",     -33.8568,  151.2153),
    ("Eiffel Tower",            48.8584,    2.2945),
    ("Times Square",            40.7580,  -73.9855),
    ("International Waters",     0.0000,  -30.0000),  # may return 404
]

with Geo(api_key="tk_...") as geo:
    for name, lat, lon in coordinates:
        try:
            result = geo.timezone_by_coords(lat=lat, lon=lon)
            print(f"{name}: {result['timezone']} (UTC{result['utc_offset']}, DST: {result['is_dst']})")
        except Exception as exc:
            print(f"{name}: {exc}")

Output:

Sydney Opera House: Australia/Sydney (UTC+10:00, DST: False)
Eiffel Tower: Europe/Paris (UTC+02:00, DST: True)
Times Square: America/New_York (UTC-04:00, DST: True)
International Waters: No timezone found for coordinates (0.0, -30.0). This may be in international waters.

Get timezone from an IP address¶

Combine ip_lookup and timezone_by_coords to get the precise IANA timezone for any IP:

from toolkitapi import Geo

def timezone_for_ip(ip: str) -> str:
    with Geo(api_key="tk_...") as geo:
        loc = geo.ip_lookup(ip)
        tz = geo.timezone_by_coords(lat=loc["latitude"], lon=loc["longitude"])
    return tz["timezone"]

print(timezone_for_ip("8.8.8.8"))    # "America/Los_Angeles"
print(timezone_for_ip("1.1.1.1"))    # "Australia/Brisbane"

Inspect timezone details¶

timezone_info returns the current UTC offset, DST status, and local time for any IANA timezone name.

from toolkitapi import Geo

timezones_to_check = [
    "America/New_York",
    "Europe/London",
    "Asia/Kolkata",
    "Pacific/Auckland",
]

with Geo(api_key="tk_...") as geo:
    for tz in timezones_to_check:
        info = geo.timezone_info(tz)
        dst_flag = " (DST active)" if info["is_dst"] else ""
        print(f"{tz:25} UTC{info['utc_offset']:7}  {info['local_time']}{dst_flag}")

Display local time for a user¶

from toolkitapi import Geo

def get_user_local_time(ip: str) -> dict:
    """Return the current local time and timezone for a visitor's IP."""
    with Geo(api_key="tk_...") as geo:
        loc = geo.ip_lookup(ip)
        tz_coords = geo.timezone_by_coords(lat=loc["latitude"], lon=loc["longitude"])
        tz_details = geo.timezone_info(tz_coords["timezone"])
    return {
        "timezone": tz_details["timezone"],
        "local_time": tz_details["local_time"],
        "utc_offset": tz_details["utc_offset"],
        "city": loc.get("city"),
    }

info = get_user_local_time("8.8.8.8")
print(f"Visitor is in {info['city']} — local time: {info['local_time']} ({info['timezone']})")

Response Fields¶

timezone-convert response:

timezone-by-coords response:

timezone-info response: