Timezone Conversion for Global Applications

The Timezone Problem

There are 600+ named timezones. They don't follow clean geographic boundaries, they observe daylight saving time on different dates, and some offset by 30 or 45 minutes rather than a full hour.

Handling this correctly requires an up-to-date timezone database (IANA tzdata), not hardcoded UTC offsets.

Why UTC Offsets Aren't Enough

UTC+1 is ambiguous — it could be CET (Central European Time, no DST in winter) or BST (British Summer Time, in effect during summer). The same offset applies to different real times depending on the date and location.

Always work with IANA timezone names (Europe/London, America/New_York) and convert to offsets only when necessary for display.

API Usage

curl -X POST https://api.toolkitapi.io/v1/geo/timezone-convert \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "2026-03-29T10:00:00",
    "from_tz": "America/New_York",
    "to_tz": "Asia/Tokyo"
  }'

{
  "original": "2026-03-29T10:00:00",
  "from_tz": "America/New_York",
  "to_tz": "Asia/Tokyo",
  "converted": "2026-03-29T23:00:00",
  "offset_from": "-04:00",
  "offset_to": "+09:00",
  "dst_active_from": true,
  "dst_active_to": false
}

Coordinate-Based Timezone Lookup

If you have GPS coordinates but not a timezone name, the API resolves the timezone from the location:

{ "lat": 35.6895, "lng": 139.6917 }
→ { "timezone": "Asia/Tokyo", "offset": "+09:00" }

Common Pitfalls

• Storing timestamps as local time — always store in UTC, convert on display
• Hardcoding DST transition dates — they change by government decree; use the API
• Ignoring historical data — timezone rules change; a timestamp from 2019 may use different rules than today