Unix Timestamp & Epoch Time: The Developer's Complete Guide

What Is a Unix Timestamp?

A Unix timestamp (also called epoch time, POSIX time, or simply Unix time) is a system for tracking time as a single integer: the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC. That reference point is called the Unix epoch.

For example, the timestamp 1700000000 represents November 14, 2023, at 22:13:20 UTC. The timestamp 0 represents the epoch itself. Negative timestamps represent dates before 1970: -86400 is December 31, 1969.

This system is elegant in its simplicity. A single integer is easy to store in databases, compare for sorting, transmit in APIs, and convert to any local time zone. Every programming language, database, and operating system supports Unix timestamps natively.

Why Timestamps Matter for Developers

Unix timestamps solve four fundamental problems in software development:

1. Time zone independence — A timestamp is always UTC. No ambiguity about "3 PM" — whose 3 PM? The timestamp 1700000000 is the same moment everywhere on Earth.
2. Easy arithmetic — Want to know the time 24 hours from now? Add 86400 (the number of seconds in a day). Need the difference between two events? Subtract their timestamps.
3. Database efficiency — An integer takes 4 or 8 bytes of storage and is blazingly fast to index, sort, and compare. Date strings take 10–25 bytes and require parsing.
4. API standardization — When your frontend (JavaScript), backend (Python/PHP), and database (PostgreSQL/MySQL) all speak the same timestamp format, conversion bugs vanish.

Seconds vs. Milliseconds: The 10-Digit vs. 13-Digit Problem

This is the single most common timestamp bug. Some systems use seconds (10 digits) and others use milliseconds (13 digits):

If you pass a millisecond timestamp to a function expecting seconds, you get a date in the year 55,000+. If you pass seconds to a millisecond function, you get a date in January 1970. Always check the documentation for the expected unit, and convert explicitly when crossing language boundaries:

// JavaScript: milliseconds to seconds
const seconds = Math.floor(Date.now() / 1000);

// JavaScript: seconds to milliseconds
const ms = secondsTimestamp * 1000;

// Python: seconds to milliseconds
ms = int(time.time() * 1000)

// PHP: milliseconds to seconds
$seconds = intdiv($milliseconds, 1000);

Converting Timestamps in Every Language

JavaScript

// Current timestamp (seconds)
const now = Math.floor(Date.now() / 1000);

// Timestamp → Date string
const date = new Date(1700000000 * 1000);
console.log(date.toISOString()); // "2023-11-14T22:13:20.000Z"
console.log(date.toLocaleString()); // Local format

// Date string → Timestamp
const ts = Math.floor(new Date("2023-11-14T22:13:20Z").getTime() / 1000);

Python

import time, datetime

# Current timestamp
now = int(time.time())

# Timestamp → Date
dt = datetime.datetime.fromtimestamp(1700000000, tz=datetime.timezone.utc)
print(dt.isoformat())  # "2023-11-14T22:13:20+00:00"

# Date → Timestamp
ts = int(datetime.datetime(2023, 11, 14, 22, 13, 20,
         tzinfo=datetime.timezone.utc).timestamp())

PHP

// Current timestamp
$now = time();

// Timestamp → Date
echo date('Y-m-d H:i:s', 1700000000); // "2023-11-14 22:13:20"
echo date('c', 1700000000);            // ISO 8601 format

// Date → Timestamp
$ts = strtotime('2023-11-14 22:13:20 UTC');

SQL (MySQL / PostgreSQL)

-- MySQL
SELECT UNIX_TIMESTAMP();                          -- Current
SELECT FROM_UNIXTIME(1700000000);                 -- → Date
SELECT UNIX_TIMESTAMP('2023-11-14 22:13:20');     -- Date →

-- PostgreSQL
SELECT EXTRACT(EPOCH FROM NOW())::integer;        -- Current
SELECT TO_TIMESTAMP(1700000000);                  -- → Date
SELECT EXTRACT(EPOCH FROM TIMESTAMP '2023-11-14 22:13:20 UTC');

The Year 2038 Problem

Many older systems store Unix timestamps as signed 32-bit integers. The maximum value of a signed 32-bit integer is 2,147,483,647, which corresponds to January 19, 2038, at 03:14:07 UTC.

One second later, the timestamp overflows to -2,147,483,648, which represents December 13, 1901. This is the "Year 2038 problem" — analogous to the Y2K bug, but for Unix systems.

The fix is straightforward: use 64-bit integers. A signed 64-bit timestamp can represent dates up to the year 292,277,026,596. Most modern operating systems (Linux kernel 5.6+, macOS, Windows), 64-bit programming languages, and databases already use 64-bit timestamps. However, embedded systems, legacy code, and 32-bit file formats may still be vulnerable.

When designing APIs or database schemas today, always use 64-bit integers (BIGINT in SQL, int64 in Go, long in Java) for timestamps. This costs only 4 extra bytes per value and eliminates the 2038 risk entirely.

Timestamps in Databases: Best Practices

• Store as UTC — Always store timestamps in UTC. Convert to local time zones only at the display layer. This prevents bugs when users move between time zones or when daylight saving time changes.
• Use the native timestamp type — PostgreSQL's TIMESTAMPTZ, MySQL's TIMESTAMP, and MongoDB's ISODate are optimized for date queries and indexing.
• Index timestamp columns — Queries like "get records from the last 7 days" are extremely common. Without an index, they require a full table scan.
• Use created_at and updated_at — Two timestamps per record: when it was created and when it was last modified. Most ORMs set these automatically.
• Consider UUIDv7 for primary keys — UUID v7 embeds a millisecond-precision timestamp in the ID itself, making records inherently sortable by creation time without a separate timestamp column.

Timestamps in APIs

When designing APIs, you have two common choices for representing time:

Many APIs use both: Unix timestamps for internal fields (created_at, expires_at) and ISO 8601 for display fields (event_date, scheduled_for). Whichever you choose, document it clearly and be consistent across all endpoints.

For encoding timestamps or any data in URLs and API payloads, our URL Encoder and Base64 Encoder ensure safe transmission across all systems.

Frequently Asked Questions

Conclusion

Unix timestamps are the universal language of time in computing. They solve time zone ambiguity, enable simple date arithmetic, and provide efficient database storage. The key rules: always store in UTC, always know whether you are working in seconds or milliseconds, use 64-bit integers to avoid the 2038 problem, and convert to human-readable formats only at the display layer.

For timestamp-based unique identifiers, generate UUID v7 — they embed millisecond timestamps for natural chronological sorting. For formatting API data, use our JSON Formatter to validate and inspect timestamp fields. And for extracting timestamps from log files, build patterns with our Regex Tester.