DevLab
Time

Unix Timestamps vs ISO 8601: Which to Use in Your API?

Compare Unix epoch timestamps with ISO 8601 strings for API design, database storage, and JavaScript date handling — with a clear recommendation.

What is a Unix Timestamp?

A Unix timestamp is the number of seconds (or milliseconds) elapsed since January 1, 1970 00:00:00 UTC. It is a simple integer: 1749812400. Every timezone sees the same number for the same moment — no ambiguity.

Direct Comparison

PropertyUnix TimestampISO 8601
Example17498124002026-06-13T10:30:00Z
Human readableNoYes
Timezone ambiguityNoneNone (with Z)
Storage size4-8 bytes (int)~24 bytes (string)
Duration mathSubtract two integersRequires Date parsing
Year 2038 problemOnly with 32-bit intNo limit

When to Use Unix Timestamps

  • Redis TTL values and integer-based expiry systems
  • Mathematical calculations: duration = timestamp2 - timestamp1
  • High-throughput databases where integer comparison beats string parsing
  • Unix system calls and tools that natively use epoch time

When to Use ISO 8601

  • Public APIs — human-readable, easy to inspect in logs
  • Date-only values (2026-06-13) — Unix timestamps have no meaning without a time component
  • User-facing data exports (CSV, JSON reports)
  • PostgreSQL timestamptz columns (natively return ISO format)

JavaScript Conversion

// Unix seconds → Date
const d = new Date(1749812400 * 1000);  // multiply by 1000 for ms

// Date → Unix seconds
const unix = Math.floor(Date.now() / 1000);

// Date → ISO 8601
new Date().toISOString();  // "2026-06-13T10:30:00.000Z"

// ISO 8601 → Unix seconds
Math.floor(new Date("2026-06-13T10:30:00Z").getTime() / 1000);

Recommendation

Use ISO 8601 in public APIs and logs — human-readable is worth the extra bytes. Use Unix timestamps internally for high-throughput date-time columns. Always store UTC, convert to local time only at the UI layer.

Practice with these tools

More Learning Topics