Introduction

Unix timestamps (also called epoch time) are the standard way computers represent time. You'll encounter them in APIs, databases, logs, and configuration files. Understanding timestamps helps you debug time-related issues, convert between formats, and work with time-based data across different systems.

What is a Unix Timestamp?

A Unix timestamp is the number of seconds that have elapsed since January 1, 1970 (the Unix epoch). This single integer represents any moment in time, making it ideal for storage and computation.

Key Facts

Epoch StartJanuary 1, 1970, 00:00:00 UTC

UnitSeconds (or milliseconds in some systems)

Example1704067200 = Jan 1, 2024

RangeNegative for dates before 1970

Why Use Timestamps?

Universal FormatWorks across all programming languages and systems. No timezone confusion.
Easy ArithmeticSubtract timestamps to get duration. Add seconds to shift time. Simple math.
Compact StorageA single integer takes less space than formatted date strings.

Common Date/Time Formats

Format	Example	Use Case
Unix Timestamp	1704067200	APIs, databases, logs
ISO 8601	2024-01-01T00:00:00Z	JSON APIs, web standard
Milliseconds	1704067200000	JavaScript, Java
RFC 2822	Mon, 01 Jan 2024 00:00:00 GMT	Email headers
Custom	2024-01-01 12:00 AM	User display

Practical Use Cases

Debugging APIs

When an API returns timestamps, convert them to readable dates to verify expiration times, scheduling, and time-based logic.

Log Analysis

Server logs often use timestamps. Convert them to local time to understand when errors occurred and correlate events.

JWT Tokens

JWT expiration is stored as timestamps. Decode and check if tokens are still valid before processing requests.

Database Queries

Query data by time range using timestamps. Calculate age, duration, or filter records by date boundaries.

Converting Timestamps in Code

Every language has its own way of handling timestamps. Here are the most common operations: getting the current timestamp, converting from timestamp to date, and converting from date to timestamp.

JavaScript

// Current timestamp (milliseconds)
Date.now();                        // 1704067200000

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

// Timestamp to date
new Date(1704067200 * 1000);       // Mon Jan 01 2024 ...

// Date to timestamp
new Date('2024-01-01').getTime() / 1000;

Python

import time
from datetime import datetime

# Current timestamp (seconds)
int(time.time())                   # 1704067200

# Timestamp to date
datetime.fromtimestamp(1704067200) # datetime(2024, 1, 1, 0, 0)

# Date to timestamp
int(datetime(2024, 1, 1).timestamp())

Go

import "time"

// Current timestamp (seconds)
time.Now().Unix()                  // 1704067200

// Timestamp to time
time.Unix(1704067200, 0)

// Time to timestamp
time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC).Unix()

Common Timestamp Pitfalls

Timestamps seem simple, but they hide several traps that cause real bugs in production:

Seconds vs Milliseconds

JavaScript uses milliseconds, while Unix timestamps are seconds. Forgetting to multiply or divide by 1000 is the most common timestamp bug. A timestamp of 1704067200 in JavaScript gives you January 1970 instead of January 2024.

Timezone Confusion

Timestamps are always UTC, but displaying them without timezone conversion leads to off-by-one-day errors. Always convert to local time for display and store in UTC. Use ISO 8601 with timezone offset (e.g., 2024-01-01T00:00:00-05:00) when you need to preserve timezone info.

The Year 2038 Problem

32-bit signed integers overflow at 2147483647, which is January 19, 2038. Systems still using 32-bit timestamps will break. Most modern systems have migrated to 64-bit, but embedded systems and legacy code may still be at risk.

Leap Seconds

Unix timestamps do not account for leap seconds. This means a day with a leap second has 86401 seconds but the timestamp only counts 86400. Most applications ignore this, but high-precision systems need to handle it.

Real-world Example: Debugging an API Response

You receive a JWT token from an API and need to check if it is expired. The token payload contains timestamps in seconds:

// JWT payload (decoded)
{
  "sub": "user123",
  "iat": 1704067200,   // Issued at: Jan 1, 2024
  "exp": 1704153600    // Expires: Jan 2, 2024
}

// Check expiration in JavaScript
const now = Math.floor(Date.now() / 1000);
if (payload.exp < now) {
  console.log("Token expired!");
} else {
  const remaining = payload.exp - now;
  console.log(`Token valid for ${remaining} more seconds`);
}

This is a common pattern in authentication systems. The iat (issued at) and exp (expiration) claims use Unix timestamps in seconds. Always compare against the current time in the same unit.

Quick Tips

JavaScript uses milliseconds: multiply Unix timestamp by 1000
Timestamps are always UTC - convert to local time for display
32-bit timestamps overflow in 2038 (use 64-bit for future-proofing)
ISO 8601 with timezone: 2024-01-01T00:00:00-05:00
Current timestamp: ~1.7 billion seconds since 1970

Written by Zhisan

Independent Developer · Last updated June 2026

Timestamp Guide: Unix Time Explained