Skip to main content
Dev Utilities Pro

Methodology · Timestamp Formats

Unix timestamp conversion methodology

Reviewed by · Last reviewed .

A Unix timestamp is an integer count of seconds (or milliseconds, in many modern APIs) elapsed since the Unix epoch: 1970-01-01T00:00:00Z. The epoch is defined in POSIX.1-2017 §4.16 as “the number of seconds elapsed since the Epoch, excluding leap seconds.” That “excluding leap seconds” clause is load-bearing — it means Unix time is not a strict count of SI seconds and cannot be used directly for sub-second precision timing across leap second boundaries. For scheduling, logging, and duration arithmetic — the common use cases — this distinction does not matter. This page explains the conversion algorithms behind the Dev Utilities Pro Unix Timestamp Converter.

Seconds vs. milliseconds auto-detection

The converter automatically detects whether an integer input represents Unix seconds or Unix milliseconds. The detection rule is:

if abs(input) >= 10^12:
  unit = milliseconds
  unixSeconds = input / 1000
else:
  unit = seconds
  unixSeconds = input

This threshold is not arbitrary. The Unix timestamp crossed 109 (1 billion seconds) on September 9, 2001 at 01:46:40 UTC. As of 2026, all Unix second timestamps are 10 digits. Unix millisecond timestamps are 13 digits. No second-resolution timestamp will reach 1012 until November 20, 33658 AD. The auto-detection rule is therefore unambiguous for any timestamp representable in a 64-bit integer within the plausible range of use.

Negative timestamps (dates before the 1970 epoch) follow the same rule: timestamps less than −1012 are treated as milliseconds. The earliest representable date in a signed 64-bit Unix timestamp is approximately −292 billion years, but the converter surfaces a warning for inputs outside the range −62135596800 to 253402300799 (the range of representable dates in ISO 8601 without year-number extensions).

Conversion algorithm: Unix timestamp → ISO 8601

The converter uses the proleptic Gregorian calendar algorithm for Unix timestamp to civil date conversion. The algorithm works as follows:

// Input: unixSeconds (integer or float for sub-second precision)

Step 1 — Compute Julian Day Number (JDN)
  // Days since the Unix epoch
  days = floor(unixSeconds / 86400)
  secondsInDay = unixSeconds mod 86400  // 0–86399

Step 2 — Compute year, month, day using Fliegel-Van Flandern (1968)
  // Extended algorithm for proleptic Gregorian calendar
  Z = days + 2440588  // Julian Day Number of 1970-01-01
  W = floor((Z - 1867216.25) / 36524.25)
  X = W - floor(W / 4)
  B = Z + 1525 + X
  C = floor((B - 122.1) / 365.25)
  D = floor(365.25 * C)
  E = floor((B - D) / 30.6001)

  day   = B - D - floor(30.6001 * E)
  month = E - 1  (if E < 14) OR E - 13  (if E >= 14)
  year  = C - 4716  (if month > 2) OR C - 4715  (if month <= 2)

Step 3 — Compute hour, minute, second from secondsInDay
  hour   = floor(secondsInDay / 3600)         // 0–23
  minute = floor((secondsInDay mod 3600) / 60) // 0–59
  second = secondsInDay mod 60                 // 0–59

Step 4 — Format as ISO 8601
  "YYYY-MM-DDTHH:mm:ssZ"
  // Zero-pad all components to required widths

In practice, the converter delegates this computation to the JavaScript Date object (ECMAScript 2024 §21.4), which implements the same proleptic Gregorian calendar. The algorithm above documents the underlying math for auditability. The ECMAScript Date specification precisely mirrors POSIX.1-2017 §4.16 — both exclude leap seconds and use the same epoch.

ISO 8601 and RFC 3339 formatting

ISO 8601:2004 defines the international standard for date and time representation. RFC 3339 is a strict profile of ISO 8601 designed for internet timestamps, used in HTTP headers, RSS/Atom feeds, OpenAPI 3.x schemas, and most modern REST APIs. Key differences:

  • ISO 8601 allows a space separator between date and time, truncated representations (YYYY, YYYY-MM, HH:mm), week dates (2026-W21-5), and ordinal dates (2026-143). It also permits comma as a decimal separator for fractional seconds.
  • RFC 3339 requires the T separator (no space), mandates including seconds, prohibits truncated forms, requires a timezone designator (Z or ±HH:mm), and uses a period (not comma) for fractional seconds. Example: 2026-05-23T15:30:00.000Z.

The converter outputs both ISO 8601 UTC (with Zsuffix) and RFC 3339 with the user's selected timezone offset. When the selected timezone observes DST, the displayed UTC offset reflects the offset at the specific moment represented by the timestamp — not a fixed offset.

IANA timezone normalization

The IANA Time Zone Database (tzdata, maintained at iana.org/time-zones) is the authoritative source for civil timezone rules, including Daylight Saving Time transition dates, historical timezone changes, and the mapping from timezone names to UTC offsets. The converter uses the IANA database bundled with the user's browser via the ECMAScript Intl.DateTimeFormat API.

Timezone abbreviations (EST, PST, CST, IST) are ambiguous and not accepted as input. The converter requires IANA timezone names (e.g., America/Chicago, Asia/Kolkata,Europe/Berlin). The selector surfaces the canonical IANA name alongside the current UTC offset and common abbreviation for user guidance.

Y2K38 overflow computation

The Year 2038 problem (Y2K38) affects systems that store Unix timestamps in signed 32-bit integers. The maximum value of a signed 32-bit integer is 2,147,483,647, which corresponds to 2038-01-19T03:14:07Z. The next second — 2,147,483,648 — overflows to −2,147,483,648, representing December 13, 1901 at 20:45:52 UTC.

The converter computes the distance to the Y2K38 threshold for any input timestamp and surfaces a warning banner when the input is within one year of the overflow point (i.e., timestamp > 2,115,947,647 seconds ≈ 2037-01-19). The computation is:

Y2K38_THRESHOLD = 2_147_483_647  // 2038-01-19T03:14:07Z

distance_seconds = Y2K38_THRESHOLD - unixSeconds
distance_days    = floor(distance_seconds / 86400)

if distance_seconds < 0:
  // Input timestamp is past the 32-bit overflow point
  // Show: "This timestamp exceeds the signed 32-bit limit and
  //         will cause overflow on systems using 32-bit time_t."

if distance_seconds < 31_536_000:  // less than 1 year
  show Y2K38 warning banner

Modern 64-bit systems are not affected: a signed 64-bit Unix timestamp can represent dates up to approximately 292,277,026,596 years from now. MySQL TIMESTAMP columns remain affected (32-bit storage); MySQL DATETIME columns are not. PostgreSQL TIMESTAMP columns use 64-bit storage and are not affected.

Reverse conversion: date/time → Unix timestamp

The reverse path (civil date-time to Unix timestamp) applies the same proleptic Gregorian calendar algorithm in reverse:

// Input: year, month, day, hour, minute, second, timezone offset (minutes)

Step 1 — Compute Julian Day Number from civil date
  a = floor((14 - month) / 12)
  y = year + 4800 - a
  m = month + 12 * a - 3
  JDN = day + floor((153 * m + 2) / 5) + 365 * y
      + floor(y / 4) - floor(y / 100) + floor(y / 400) - 32045

Step 2 — Days since Unix epoch (JDN 2440588)
  days = JDN - 2440588

Step 3 — Seconds in day (UTC)
  secondsInDay = hour * 3600 + minute * 60 + second - (tzOffset * 60)

Step 4 — Unix timestamp
  unixSeconds = days * 86400 + secondsInDay

In practice the converter uses Date.UTC()from ECMAScript (which operates in UTC) and adjusts for the user-specified timezone offset. DST ambiguity in the “fall back” hour (when a given local wall-clock time occurs twice) is resolved by the IANA database — the converter shows both candidate UTC timestamps and asks the user to select the intended one.

Assumptions

  • Leap seconds are excluded per POSIX.1-2017 §4.16 — Unix time is not a monotonic count of SI seconds. The converter does not account for the ~27 leap seconds inserted since 1972.
  • The proleptic Gregorian calendar is extended backward before its 1582 adoption for historical dates — Julian calendar corrections are not applied.
  • Millisecond auto-detection threshold is 1012. Inputs near this boundary (1012 ± 109) are flagged with an ambiguity note.
  • Timezone data is sourced from the IANA database version bundled with the user's browser — converter behavior for future DST rule changes depends on the browser's tzdata currency.

Limitations

  • Sub-millisecond precision (microseconds, nanoseconds) is not supported — JavaScript Date has millisecond resolution.
  • Dates before 100 CE and after 9999 CE may not format correctly in ISO 8601 without year-number extensions (per ISO 8601-1:2019 §4.3.2).
  • Historical timezone conversions before 1970 rely on IANA historical data, which is incomplete for some regions before the 20th century.

Primary sources

Last reviewed by Byron Malone, 2026-05-23. This methodology document explains the conversion algorithms used by the Dev Utilities Pro Unix Timestamp Converter. Always verify outputs against your runtime environment — timezone data currency depends on your OS and browser updates.

Back to methodology overview.