Unix Timestamps Explained: How to Convert Epoch Time to a Date

Every API response you have ever seen with a field like created_at: 1700000000is using a Unix timestamp. It is just a number — but understanding what that number means, which format it is in, and how to convert it is essential for any developer working with time-based data.

What is a Unix timestamp?

A Unix timestamp (also called Epoch time or POSIX time) is the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC — a reference point known as the Unix Epoch. It is timezone-independent, unambiguous, and easy to store as a single integer, which is why virtually every programming language, database, and API uses it.

Seconds vs milliseconds

This is the most common source of bugs. Traditional Unix timestamps use secondsand are 10 digits long (e.g. 1700000000). JavaScript’s Date.now() returns milliseconds and is 13 digits long (e.g. 1700000000000). If you pass a milliseconds timestamp to an API expecting seconds, you will get a date around the year 57,000.

The timestamp converter auto-detects the format: 10 digits → seconds, 13 digits → milliseconds.

How to convert in code

JavaScript: new Date(ts * 1000) for seconds, or new Date(ts) for milliseconds. To get the current timestamp: Math.floor(Date.now() / 1000).

Python: datetime.fromtimestamp(ts, tz=timezone.utc). Current timestamp: int(time.time()).

PHP: date('Y-m-d H:i:s', $ts). Current: time().

SQL (PostgreSQL): TO_TIMESTAMP(ts). MySQL: FROM_UNIXTIME(ts).

The Year 2038 problem

32-bit systems store timestamps as a signed 32-bit integer. The maximum value is 2,147,483,647 — which represents January 19, 2038, 03:14:07 UTC. After that, the counter overflows to a large negative number. This is the “Year 2038 problem” (analogous to the Y2K bug for 32-bit time).

Modern 64-bit systems, JavaScript, Python, and most current databases are not affected. If you are maintaining embedded systems or legacy C code, this is worth auditing.

ISO 8601 and UTC

When you need a human-readable, unambiguous timestamp in text form, use ISO 8601: 2024-11-14T22:13:20Z. The trailing Z means UTC. This format sorts lexicographically (string sort = chronological sort), which makes it ideal for log files, database fields, and API responses.