Timestamp Diff Calculator

Working with timestamps — Unix epoch, ISO 8601, and the time-zone traps that haunt every backend

Time is the single most error-prone primitive in software. Time zones, daylight saving, leap seconds, leap years, locale calendars, and the inconsistent way languages handle "now" all combine into a category of bugs that show up at 02:00 on the second Sunday in March and again on the first Sunday in November. This guide is the working reference for the two formats you actually need (Unix epoch and ISO 8601), the duration calculations that bite teams, and the language-by-language code that does it correctly.

Unix epoch — what it actually is

Unix time is the number of seconds elapsed since 1970-01-01T00:00:00 UTC (the "epoch"). It is the universal time format in databases, APIs, log files, and inter-service messaging because it is:

• Always UTC. No time zone ambiguity.
• Monotonic. A larger number is always later in time.
• Sortable. Numeric ordering matches chronological ordering.
• Compact. A 32-bit signed integer covers 1901 → 2038.

The two common widths:

• 10 digits = seconds. Used by Unix tools, Postgres timestamps, most APIs. Auto-detected by length.
• 13 digits = milliseconds. Used by JavaScript's Date.now(), Java's System.currentTimeMillis(), Kafka.
• 16 / 19 digits = microseconds / nanoseconds. Used by Postgres timestamp(6), Go's time.Now().UnixNano().

The Year-2038 problem (Y2K38)

A 32-bit signed integer storing seconds-since-1970 overflows on 2038-01-19T03:14:07 UTC. After that moment, naive 32-bit Unix time wraps to -2,147,483,648 (December 1901). This affects:

• Embedded systems and IoT devices using 32-bit time_t.
• Old SQL databases with INT timestamp columns.
• Some MySQL DATETIME columns prior to 5.6.
• 32-bit file systems (ext2, ext3 inode timestamps).

Modern systems use 64-bit time_t, which gives ~292 billion years of headroom. If you ship to embedded systems or maintain legacy software, audit for 32-bit time storage now — the failure mode is silent and starts hitting 30-year mortgages and 20-year insurance contracts already.

ISO 8601 — the human-readable companion

ISO 8601 is the international standard for date/time representation. The canonical forms:

• 2026-05-02 — date only.
• 2026-05-02T14:30:00Z — full datetime in UTC (the Z means "Zulu", i.e. UTC).
• 2026-05-02T14:30:00+05:00 — full datetime with explicit offset.
• 2026-05-02T14:30:00.123Z — millisecond precision.
• P1Y2M10DT2H30M — duration: 1 year, 2 months, 10 days, 2 hours, 30 minutes.

Always include the timezone marker (Z or ±HH:MM). A bare 2026-05-02T14:30:00 is ambiguous — different parsers interpret it as UTC vs local vs throw an error.

Computing durations — the two correct approaches

Duration calculations work cleanly in two regimes:

1. Fixed-length units (seconds, minutes, hours, days, weeks) — just subtract the timestamps and divide. A "day" in this regime is exactly 86,400 seconds, regardless of DST or calendar.
2. Calendar units (months, years) — depend on which months are involved. "One month from January 31" can mean Feb 28, Mar 1, Mar 2, or Mar 3 depending on the rule. Use a real datetime library, not arithmetic.

The conversion table for fixed units:

Duration calculations across 6 languages

const a = new Date('2026-05-02T09:00:00Z');
const b = new Date('2026-05-02T11:30:00Z');
const seconds = (b - a) / 1000;        // 9000
const minutes = seconds / 60;           // 150
const hours   = minutes / 60;           // 2.5

from datetime import datetime, timezone
a = datetime(2026, 5, 2, 9, 0, tzinfo=timezone.utc)
b = datetime(2026, 5, 2, 11, 30, tzinfo=timezone.utc)
delta = b - a                  # timedelta(seconds=9000)
print(delta.total_seconds())   # 9000.0

import "time"
a, _ := time.Parse(time.RFC3339, "2026-05-02T09:00:00Z")
b, _ := time.Parse(time.RFC3339, "2026-05-02T11:30:00Z")
diff := b.Sub(a)               // 2h30m0s
seconds := diff.Seconds()      // 9000

import java.time.*;
Instant a = Instant.parse("2026-05-02T09:00:00Z");
Instant b = Instant.parse("2026-05-02T11:30:00Z");
Duration d = Duration.between(a, b);   // PT2H30M
long secs = d.getSeconds();

use chrono::{DateTime, Utc};
let a: DateTime<Utc> = "2026-05-02T09:00:00Z".parse().unwrap();
let b: DateTime<Utc> = "2026-05-02T11:30:00Z".parse().unwrap();
let d = b - a;                  // Duration
let secs = d.num_seconds();     // 9000

SELECT EXTRACT(EPOCH FROM ('2026-05-02 11:30:00+00'::timestamptz
                       -  '2026-05-02 09:00:00+00'::timestamptz))
AS seconds_diff;   -- 9000

Time-zone gotchas — what bites every team

• DST transitions. On the spring-forward day, 02:00 local time does not exist; on fall-back, 01:30 happens twice. "Today minus 24 hours" can equal yesterday OR the day before.
• Naive Date in JavaScript. new Date('2026-05-02') parses as midnight UTC; new Date(2026, 4, 2) parses as midnight local time. Different result, no warning.
• Server timezone vs database timezone vs app timezone. If any two disagree, all queries lie. Set everything to UTC and convert at the edge.
• Daylight saving in cron. Linux cron can skip a job (during spring-forward) or run it twice (during fall-back). Schedulers that respect named time zones (kubernetes CronJob with spec.timeZone) avoid this.
• Time zone naming differences. "EST" can mean Eastern Standard Time or Australian Eastern Standard Time. Always use IANA tz names: America/New_York, not EST.
• Leap seconds. UTC has occasional leap seconds (61 since 1972) that Unix time mostly ignores. NTP and POSIX both fudge them; if you need true monotonic time, use CLOCK_MONOTONIC.

Practical use cases for timestamp diff

• API response time: log request_start and response_end timestamps; diff gives latency.
• Session duration: when a user logged in vs logged out.
• Cache TTL verification: compare created_at with now(); if greater than TTL, evict.
• Token expiration check: compare exp claim with current time.
• Build-pipeline duration: CI starts at T1, finishes at T2; diff is the build time.
• SLA reporting: incident detected at T1, resolved at T2; diff feeds MTTR metrics.
• Lead-time tracking: commit time vs deploy time = DORA "lead time for changes".

Common timestamp mistakes

• Mixing 10-digit and 13-digit timestamps. Subtracting 1714660000 (seconds) from 1714660000000 (ms) without converting gives a meaningless result.
• Storing local-time strings in databases. "2026-05-02 14:00:00" without TZ is a bug waiting to happen. Use timestamptz in Postgres, DATETIME WITH TIME ZONE, or store ISO 8601 with explicit offset.
• Computing months as 30 days. February has 28; July has 31. Always round-trip through a real datetime library.
• Trusting Date.parse() on partially-formed strings. Browsers vary in tolerance; Safari is stricter than Chrome. Always pass full ISO 8601.
• Forgetting microsecond precision in databases. Postgres stores microseconds; if you compare a JS millisecond timestamp against a Postgres timestamp, you may miss matches by a microsecond.
• Using Date.now() for benchmarks. The system clock can jump backward (NTP correction). For elapsed-time measurement use performance.now() in browsers or CLOCK_MONOTONIC on Linux.