Working with Time Zones: A Developer's Guide to Dates and Times

Time is one of those concepts that feels simple until you try to write software that handles it correctly. A second is a second, an hour is an hour, and a day is — well, sometimes 23 hours, sometimes 25, and on one occasion in Samoa's history, a day simply did not exist at all. Time zones layer political decisions, historical accidents, and astronomical realities on top of what should be straightforward arithmetic, and they have been generating bugs for as long as software has existed. This guide is a deep dive into the landscape of time zones as it pertains to working developers, covering why they exist, how they are represented, where the pitfalls lie, and what best practices keep you out of trouble.

Why Time Zones Exist

Before the late nineteenth century, every town set its clocks to local solar noon — the moment when the sun was at its highest point in the sky. A town 50 miles to the west would have clocks running a few minutes behind, and nobody cared because travel was slow enough that the difference did not matter. The railroads changed everything. When you are trying to publish a train schedule that spans hundreds of miles, having every station on its own local time is a recipe for missed connections and collisions. In 1883, the major North American railroad companies adopted a system of four standard time zones, and most towns along the routes adjusted their clocks to match. A year later, delegates at the International Meridian Conference in Washington agreed to divide the world into 24 zones centered on the prime meridian at Greenwich, England. The system we live with today is a direct descendant of that railroad-driven compromise.

UTC, GMT, and the Prime Meridian

At the center of the modern time zone system sits Coordinated Universal Time, abbreviated UTC (a compromise between the English and French orderings of the words). UTC is the successor to Greenwich Mean Time, and for most software purposes the two are interchangeable, but they are not technically identical. GMT is defined by the position of the sun relative to the prime meridian — it is an astronomical time standard. UTC is defined by atomic clocks and is adjusted with leap seconds to stay within 0.9 seconds of astronomical time. The distinction matters to astronomers and metrologists, but for developers, the practical takeaway is simple: use UTC as your reference point, and do not worry about the sub-second difference from GMT.

The IANA Time Zone Database

Time zones are not just fixed offsets from UTC. They are named regions with rules that change over time — rules about when daylight saving time starts and ends, rules that governments revise with sometimes remarkably short notice. The authoritative source for these rules is the IANA Time Zone Database, also known as the Olson database after its original maintainer, Arthur David Olson. The database assigns each region a canonical name in the form Area/City — America/New_York, Europe/London, Asia/Kolkata, Pacific/Auckland. These names are deliberately tied to cities rather than countries or political regions because city names are more stable than political boundaries.

The database is updated multiple times a year to reflect legislative changes. When a country decides to abolish daylight saving time, adopt it, or shift its UTC offset, a new release of the IANA database captures the change. Operating systems, programming languages, and libraries ship their own copies of the database, which means that a system running an older release may not know about recent rule changes. This is one of the reasons time zone conversions can give different results on different machines — and why keeping your platform's timezone data up to date is not an optional nicety but a correctness requirement.

Offsets Are Not Enough

A common mistake among developers is to think of a time zone as a fixed offset from UTC. New York is UTC-5 in the winter and UTC-4 in the summer, so why not just store the offset? The problem is that an offset tells you what the local time is right now, but it does not tell you what the local time will be at some future date, or what it was at some past date. If you store a future appointment as "2027-03-15T14:00:00-05:00," you are asserting that New York will be at UTC-5 on that date. But if Congress changes the DST rules between now and then — which has happened before and will happen again — your stored offset will be wrong. Only the IANA zone name (America/New_York) gives you enough information to compute the correct local time for any point in the past or future, because the name is a pointer into a database of rules rather than a single static value.

This is why the distinction between a timezone-aware datetime and a timezone-naive datetime matters so much. A naive datetime is just a date and a time with no indication of what time zone it belongs to. It could be local time in Tokyo, or UTC, or the developer's best guess at the user's location. An aware datetime carries either a UTC offset or, better, a named time zone, and it unambiguously identifies a single instant in time. Mixing aware and naive datetimes in the same system is a classic source of bugs that often lie dormant until a DST transition exposes them.

The Messy Politics of Daylight Saving Time

Daylight saving time is, at its core, a political decision, and political decisions are messy. The United States has changed its DST rules multiple times — most recently in 2007, when the start date moved from the first Sunday in April to the second Sunday in March, and the end date moved from the last Sunday in October to the first Sunday in November. The European Union has been debating the abolition of seasonal clock changes since 2018, with member states unable to agree on whether to stay permanently on summer time or winter time. Countries near the equator generally do not observe DST at all because the variation in daylight hours is too small to justify the disruption. And some regions have adopted and then abandoned DST multiple times — Russia switched to permanent summer time in 2011, then switched to permanent winter time in 2014.

For developers, the practical consequence is that DST rules are not immutable laws of nature. They are legislation, and legislation changes. Your software must be able to handle historical transitions, current transitions, and the possibility that future transitions will differ from what you expect today. This is another reason to always lean on the IANA database and a well-maintained library rather than implementing DST logic yourself.

Half-Hour Zones, Quarter-Hour Zones, and the Date Line

The idealized picture of 24 one-hour zones evenly spanning the globe has little resemblance to reality. India operates on UTC+5:30, a half-hour offset that covers the entire country despite its vast east-west span. Nepal is UTC+5:45, one of the few quarter-hour offsets in use. The Chatham Islands east of New Zealand are UTC+12:45. Australia has a central time zone (UTC+9:30) that sits half an hour behind the eastern states and an hour and a half ahead of the western state. These fractional offsets are not edge cases you can ignore — they affect millions of people, and any application with an international user base will encounter them.

The International Date Line adds another layer of complexity. It roughly follows the 180th meridian but zigzags around national borders to avoid splitting countries across two calendar dates. In 2011, Samoa jumped from the east side of the date line to the west side, skipping December 30 entirely. The entire country went from December 29, Thursday, to December 31, Saturday, without experiencing a Friday. If your system needed to calculate business days in Samoa that month, a hard-coded day-counting algorithm would have given the wrong answer. Only a library backed by the IANA database would have handled it correctly.

Common Developer Mistakes

The most widespread time zone bug is storing local times in the database instead of UTC. A server in California receives a timestamp from a user in Tokyo, and the application stores it as a naive datetime without converting to UTC. Every subsequent operation — sorting, comparison, display to users in other time zones — is wrong. The fix is simple: always convert to UTC at the boundary of your system (when data comes in), store UTC, and convert back to local time at the display boundary (when data goes out). You can use Loopaloo's Timezone Converter to visualize how a single instant in time is represented across different zones, which helps build the intuition that UTC is the canonical representation and everything else is a view.

Another common mistake is performing arithmetic on local times across DST boundaries. If it is 1:30 AM on the night clocks spring forward, adding one hour does not give you 2:30 AM — it gives you 3:30 AM, because 2:00 to 3:00 does not exist. Conversely, on the night clocks fall back, 1:30 AM occurs twice, and subtracting an hour from the second occurrence of 1:30 AM does not give you 12:30 AM — it gives you the first occurrence of 1:30 AM, which is actually zero hours earlier. The only safe way to do datetime arithmetic is to convert to UTC first, perform the arithmetic in UTC (where every hour is exactly 3,600 seconds and every day is exactly 86,400 seconds), and then convert back.

A subtler mistake is using the system clock's local time zone on a server. If your application server is set to America/New_York and you write code that calls "now" without specifying UTC, you are embedding an implicit dependency on the server's configuration. Move the deployment to a data center in a different time zone, or run it in a container with a different default zone, and the behavior changes silently. Always request UTC explicitly.

Best Practices

The rules that keep you safe can be summarized in a few principles. Store all timestamps in UTC or as Unix timestamps (which are inherently UTC). You can convert Unix timestamps back to human-readable form using Loopaloo's Unix Timestamp Converter. When you need to associate a time with a user-meaningful location — a calendar event that should always happen at 9 AM in the user's local time, regardless of DST — store the IANA zone name alongside the UTC timestamp. Use timezone-aware datetime types in your programming language and database. Never perform date arithmetic on local times. And always use ISO 8601 format (2027-03-15T14:00:00Z for UTC, 2027-03-15T14:00:00-04:00 for an offset) when serializing datetimes to strings, because ISO 8601 is unambiguous, sortable, and universally understood by parsers.

JavaScript's Date Object and the Temporal Proposal

JavaScript's built-in Date object is notoriously limited. It represents an instant in time as a millisecond count since the Unix epoch (January 1, 1970, UTC), but its API mixes UTC and local-time methods on the same object, has month indices starting at zero, cannot represent timezone-aware datetimes, and parses date strings inconsistently across engines. Libraries like Moment.js (now in maintenance mode), date-fns, Luxon, and Day.js exist largely to paper over these limitations.

The Temporal proposal, which has reached Stage 3 in the TC39 process, is a ground-up replacement for Date. It introduces distinct types for the different concepts that Date conflates: Temporal.Instant for an absolute point in time, Temporal.ZonedDateTime for a timezone-aware datetime, Temporal.PlainDate for a calendar date with no time or time zone, Temporal.PlainTime for a wall-clock time with no date or time zone, and so on. Each type has well-defined arithmetic, explicit handling of DST ambiguities, and support for non-Gregorian calendars. When Temporal ships in browsers and runtimes, it will eliminate entire categories of bugs that have plagued JavaScript datetime handling for decades.

Edge Cases That Will Break Your Code

Leap seconds are inserted (or theoretically removed) to keep UTC aligned with the Earth's rotation. Unix timestamps ignore leap seconds — by definition, a Unix day is always exactly 86,400 seconds, so when a leap second occurs, the Unix timestamp effectively replays the last second. Most applications can safely ignore leap seconds, but if you are working on time-critical systems like GPS, financial trading, or scientific instrumentation, you need to be aware that the difference between UTC and TAI (International Atomic Time) grows by one second with each leap second insertion, and that not all systems agree on how to smear or step through the adjustment.

Days with 23 or 25 hours are a more immediately practical concern. On the day clocks spring forward, the day has only 23 hours. On the day clocks fall back, the day has 25 hours. If your application needs to calculate "the same time tomorrow" or "24 hours from now," those two operations will give different results on a DST transition day. "The same time tomorrow" means adding one calendar day (which could be 23 or 25 hours), while "24 hours from now" always means exactly 24 hours. Which one you want depends on your business logic, and the distinction is the kind of thing that only shows up in bug reports twice a year.

Calculating age, duration between dates, or scheduling recurring events across time zones is another minefield. Loopaloo's Date & Age Calculator handles these calculations correctly by accounting for variable-length months, leap years, and the other calendrical irregularities that make naive subtraction unreliable. If you are building similar functionality into your own application, lean on a well-tested library rather than implementing the arithmetic yourself.

Time is a human construction, layered with political decisions, historical compromises, and astronomical imprecision. Software that treats it as simple arithmetic will eventually be wrong. Software that respects the complexity — storing UTC, using named zones, relying on the IANA database, and choosing timezone-aware types — will be correct today, correct on DST transition days, and correct when a government somewhere decides to rearrange its clocks with three weeks' notice. The investment in getting time right is repaid every time your users see the correct time on their screens, regardless of where in the world they happen to be.