In-depth guide
Unix timestamp, Epoch and time representation
How to represent instants, distinguish UTC, offsets and time zones, and handle seconds, milliseconds and ISO 8601.
Epoch and absolute instants
Unix time measures time from the 1970-01-01T00:00:00Z epoch, commonly as elapsed seconds. It identifies an instant on a timeline without carrying a geographic time zone or local display format.
That neutrality is useful for storage, protocols and comparisons. Human presentation requires conversion into an appropriate calendar, locale and time zone.
Seconds, milliseconds and units
Different systems use seconds, milliseconds, microseconds or nanoseconds. Interpreting the same integer in the wrong unit can shift a date by orders of magnitude, so the unit is part of the data contract.
Many JavaScript APIs use milliseconds while traditional Unix interfaces often use seconds. Do not rely on digit-count heuristics for operational data.
UTC, offsets and time zones
UTC is the global reference; an offset such as +02:00 expresses a difference from UTC at one instant. A geographic zone such as Europe/Rome contains historical and future offset rules including daylight-saving transitions.
An offset is not a time zone. Knowing +02:00 does not tell a system what rules to apply on another date; recurring civil events usually need a zone identifier.
DST and ambiguous local times
When daylight-saving time starts, some local clock values do not exist; when it ends, some occur twice. A naive local datetime can therefore be ambiguous or invalid.
Store an absolute instant for events that happened. For future appointments tied to civil rules, preserve the local semantics and time zone as well. These are different problems.
ISO 8601 for readable interchange
ISO 8601 provides ordered, human-readable strings such as 2026-08-29T21:30:00Z or values with an explicit offset. It is often a good API and logging representation when readability matters.
Including Z or an offset avoids silent local interpretation. Contracts should still define precision, time-zone policy and the meaning of timestamps that omit an offset.
Leap seconds, ranges and best practices
The POSIX-style Unix-time model commonly used by software does not represent leap seconds as distinct linear seconds, and platforms may handle or smear them differently. Scientific systems may require stricter time scales.
Use maintained time-zone databases, state units explicitly and avoid doing civil-time arithmetic by merely adding seconds when the requirement is 'the same local time tomorrow'. Machine time and civil calendars are separate concepts.