Unix Timestamps: A Complete Guide

If you have ever stared at a number like 1700000000 in an API response and wondered what moment it represents, you have met the Unix timestamp. It is one of the most common ways to store and transmit a point in time, and also one of the most common sources of timezone bugs. This guide explains what timestamps are, how they work, and the traps that catch every developer eventually.

What a Unix timestamp is

A Unix timestamp (also called Epoch time or POSIX time) is the number of seconds that have elapsed since the Unix epoch: 00:00:00 UTC on 1 January 1970, not counting leap seconds. It is a single integer that represents a moment in time, independent of any timezone.

Because it is just a number, a timestamp is:

• Compact — fits in an integer field.
• Sortable — chronological order is numerical order.
• Timezone-independent — the same instant has the same timestamp everywhere on Earth.
• Easy to compute with — subtracting two timestamps gives the elapsed seconds.

These properties make timestamps ideal for databases, logs, file metadata, cache expiry, and API payloads. The Timestamp Converter converts between timestamps and human-readable dates in both directions.

Seconds vs milliseconds: the classic bug

Here is the trap: JavaScript uses milliseconds, most Unix systems use seconds. A timestamp captured today in seconds is 10 digits (about 1.7 billion); in milliseconds it is 13 digits (about 1.7 trillion).

If you take a millisecond timestamp and interpret it as seconds, the resulting date is tens of thousands of years in the future. If you take a seconds timestamp and interpret it as milliseconds, the date is in 1970. Both are obvious when you know to look, but in the middle of a debugging session they are surprisingly easy to miss.

The fix is to know your unit at every boundary. When a timestamp crosses from a JavaScript backend to a Python service, or from a log line to a dashboard, confirm whether it is seconds or milliseconds. Counting the digits is the fastest check: 10 digits means seconds, 13 digits means milliseconds.

Timezones and timestamps

A timestamp has no timezone. It represents the same instant worldwide. The timezone only matters when you format the timestamp into a human-readable string for display.

For example, the timestamp 1700000000 corresponds to:

• 2023-11-14 22:13:20 UTC
• 2023-11-14 17:13:20 in New York (EST, UTC-5)
• 2023-11-15 06:13:20 in Tokyo (JST, UTC+9)

The instant is identical; only the wall-clock representation differs. This is why storing timestamps (rather than local time strings) is almost always the right call for future-proof data — you convert to a local timezone only at the moment of display.

ISO 8601: the readable companion

ISO 8601 is the standard string format for dates and times, e.g. 2026-06-15T12:34:56Z. The trailing Z marks UTC; an offset like +09:00 marks another timezone. ISO 8601 is the most portable format for cross-system exchange because it carries both the instant and the timezone in a single readable string. Many APIs accept both a timestamp and an ISO string; when in doubt, prefer ISO 8601 for human-readable fields and a numeric timestamp for storage and computation.

Leap seconds: the deliberate omission

Unix time ignores leap seconds. Every day is treated as exactly 86,400 seconds long. Real astronomical time occasionally inserts a leap second to keep clock time aligned with Earth’s rotation, but Unix time pretends they do not exist. This keeps arithmetic simple at the cost of a tiny drift from true UTC. Systems that need sub-second astronomical accuracy (finance, astronomy) handle leap seconds separately; the rest of us can safely ignore them.

The Year 2038 problem

Systems that store the timestamp as a signed 32-bit integer run out of capacity on 19 January 2038 at 03:14:07 UTC. At that moment the value exceeds 2^31 - 1 and wraps to a negative number, which is interpreted as a date in December 1901.

The fix is to store timestamps in a 64-bit integer, which has capacity for hundreds of billions of years — effectively forever. Virtually all modern operating systems, databases, and languages have migrated to 64-bit storage, so the practical impact of Y2038 is small. Still, if you maintain embedded systems or legacy code, audit your timestamp storage before 2038 approaches.

Common operations

• Current timestamp — Date.now() in JavaScript returns milliseconds; time() in Python and PHP returns seconds.
• Expiry — store exp = now + ttl and compare now < exp on each request. This is exactly how JWT exp claims work (in seconds).
• Difference — subtract two timestamps to get elapsed time in the timestamp’s unit.
• Formatting — convert to an ISO string or a localized string only for display.

A practical workflow

1. Store timestamps (not local time strings) for any date you will sort, compare, or compute on.
2. Know the unit (seconds or milliseconds) at every system boundary.
3. Convert to a timezone only at display time — store and compute in UTC.
4. Use ISO 8601 when a human-readable string is needed for interchange.

When you need to inspect a timestamp found in a log, API response, or database record, paste it into the Timestamp Converter to see it in UTC, ISO, and local time at once. It is the fastest way to confirm you have the unit and the moment right.