Time is the source of more bugs in international software than perhaps any other input. Different countries use different timezones, some countries have multiple timezones, daylight saving rules vary, and political decisions can change the rules without notice. This guide covers what every developer needs to know about country timezones, with practical patterns for fetching and working with the data.
What Is a Timezone?
A timezone is a region of the world that observes a uniform standard time. Most timezones are defined relative to Coordinated Universal Time (UTC) as an offset like UTC+1, UTC-5, or UTC+5:30. The IANA Time Zone Database (also called tz database or tzdata) is the canonical source — it's used by every major operating system and programming language.
IANA timezones are named after major cities, like America/New_York, Europe/Paris, Asia/Tokyo. The reason cities are used instead of countries is that one country can span multiple timezones, and politically defined zones change less often than country borders.
Countries With Multiple Timezones
The biggest mistake when handling timezones is assuming "country = timezone". It's not true for many countries:
| Country | Number of timezones | Range |
|---|---|---|
| Russia | 11 | UTC+2 to UTC+12 |
| United States | 9 (including territories) | UTC-5 to UTC-12 |
| Canada | 6 | UTC-3:30 to UTC-8 |
| Australia | 3 (with sub-zones for DST) | UTC+8 to UTC+11 |
| Brazil | 4 | UTC-2 to UTC-5 |
| Mexico | 4 | UTC-6 to UTC-8 |
| Indonesia | 3 | UTC+7 to UTC+9 |
| Kazakhstan | 2 | UTC+5 to UTC+6 |
| Mongolia | 2 | UTC+7 to UTC+8 |
| Chile | 2 (mainland + Easter Island) | UTC-3 to UTC-6 |
If your application schedules events, sends notifications, or displays "local time", you cannot use a country-level timezone for these countries. You need to know the user's specific city or region.
Countries That Span One Timezone Despite Being Huge
Conversely, some surprisingly large countries use a single timezone for political or practical reasons:
- China — uses UTC+8 (Beijing time) for the entire country, despite spanning what would naturally be 5 timezones. Far western Xinjiang theoretically uses an unofficial UTC+6 ("Xinjiang Time") in daily life.
- India — uses UTC+5:30 (Indian Standard Time) for the entire subcontinent.
- Saudi Arabia, Iran, Afghanistan, Pakistan, Iraq — each uses a single timezone despite covering large areas.
Half-Hour and Quarter-Hour Offsets
Most timezones are offset from UTC by a whole number of hours, but several use 30-minute or 45-minute offsets. These are easy to forget:
- UTC+5:30 — India, Sri Lanka
- UTC+5:45 — Nepal
- UTC+6:30 — Myanmar, Cocos Islands
- UTC+9:30 — Australian Central Standard Time (Northern Territory, South Australia)
- UTC+12:45 — Chatham Islands (New Zealand)
- UTC-3:30 — Newfoundland, Canada
- UTC-9:30 — Marquesas Islands
If you store offsets as integers (number of hours), your code will silently corrupt time data for these regions. Always store offsets in minutes or seconds.
Daylight Saving Time (DST)
DST is where timezone bugs love to live. Some countries observe DST, some don't, and the rules can change with little notice:
- Most of Europe observes DST from the last Sunday of March to the last Sunday of October.
- The US and Canada observe DST from the second Sunday of March to the first Sunday of November (since 2007 in the US).
- Most of Africa, Asia and the equatorial belt do not observe DST.
- Australia has DST in some states (NSW, Victoria, SA, Tasmania, ACT) but not others (Queensland, WA, NT).
- Brazil abolished DST in 2019 after observing it for decades.
- Russia abolished DST in 2011, briefly considered restoring it, then settled into permanent standard time.
Never hard-code DST rules. Always use a timezone library that pulls from tzdata. Update tzdata regularly (it gets new releases ~5 times per year).
Fetching Country Timezones via REST API
Country Data API includes timezone data in every country object returned by /v1/countries. For countries with multiple timezones, the field contains a string representation of the range:
GET https://api.countrydataapi.com/v1/countries/by-code?code=US
Authorization: Bearer YOUR_API_KEY
Example response:
{
"name": "United States",
"iso2": "US",
"iso3": "USA",
"timezone": "UTC-5 to UTC-12"
}You can also filter countries by timezone:
GET https://api.countrydataapi.com/v1/countries/by-timezone?timezone=UTC%2B1
Authorization: Bearer YOUR_API_KEY
This is useful for building "countries in the same time zone as you" features, regional notification windows, or event scheduling tools.
Best Practices for Working With Timezones
1. Always store dates in UTC. Convert to the user's local timezone only at the display layer. This eliminates the entire class of "off by 5 hours" bugs.
2. Never store local time without the offset. If you must store local time (e.g., for "9 AM every day in the user's timezone"), also store the IANA timezone identifier (America/New_York) so you can recompute when DST changes or the user moves.
3. Don't rely on system locale. Server time and user time are different. Always use the user's known timezone, not new Date() on the server.
4. Use a real timezone library. JavaScript has Intl.DateTimeFormat and the new Temporal API. Python has zoneinfo (3.9+). Java has java.time. Don't roll your own.
5. Subscribe to tzdata changes. The IANA timezone database is updated several times per year as governments change their rules. Make sure your runtime is reasonably current.
Common Pitfalls
The "midnight" trap. What date does midnight belong to? In some timezones with off-by-one offsets, "midnight local time" might map to a different UTC date than you expect. Always use noon as the canonical "this date" reference if you have to convert.
Recurring events. An event that's "every Monday at 9 AM in Berlin" is not the same UTC time year-round, because Berlin observes DST. If you store it as a UTC timestamp and "increment by 7 days" you'll be off by an hour twice a year.
The Samoa jump. In December 2011, Samoa skipped December 30 to switch from UTC-11 to UTC+13 — they crossed the international date line. If your application stored "December 30, 2011 in Samoa" you ended up with a date that didn't exist.
Get Started
To fetch timezone data for your application, create a free account at CountryDataAPI. Timezone information is included in every country object alongside ISO codes, currency and phone codes. Plans start at $9.99/month with 10,000 monthly requests.
For full reference, see the countries by timezone endpoint documentation.