Understanding Timestamps: A Complete Developer Guide

What is a Timestamp?

A timestamp is a way to represent a specific point in time as a string or number. Timestamps are essential in programming for:

• Recording when events occurred (logs, user actions, transactions)
• Scheduling future events
• Comparing dates and calculating durations
• Storing dates in databases
• Communicating dates between systems via APIs

Different systems use different timestamp formats, which is why conversion tools are essential for developers.

Unix Timestamp (Epoch Time)

The Unix timestamp, also known as Epoch time, POSIX time, or Unix time, is the number of seconds that have elapsed since January 1, 1970, at 00:00:00 UTC (the "Unix Epoch").

Examples

Seconds vs Milliseconds

Unix timestamps come in two common variants:

• Seconds (10 digits): 1706745600 - used by most Unix systems, PHP, Python
• Milliseconds (13 digits): 1706745600000 - used by JavaScript, Java

Our converter automatically detects which variant you're using based on the number of digits.

Advantages of Unix Timestamps

• Timezone-independent: Always represents UTC, no timezone confusion
• Compact: Just a single number
• Easy to compare: Simple numeric comparison
• Easy math: Add seconds to get future dates

Limitations

• Not human-readable: 1706745600 means nothing at a glance
• Year 2038 problem: 32-bit systems will overflow on January 19, 2038
• No timezone info: Can't tell what local time it represents

ISO 8601 Format

ISO 8601 is an international standard for representing dates and times. It's the most widely recommended format for data interchange.

Format Structure

YYYY-MM-DDTHH:mm:ss.sssZ
YYYY-MM-DDTHH:mm:ss±HH:MM

• YYYY: 4-digit year
• MM: 2-digit month (01-12)
• DD: 2-digit day (01-31)
• T: Separator between date and time
• HH:mm:ss: Hours, minutes, seconds
• .sss: Optional milliseconds
• Z: UTC timezone (Zulu time)
• ±HH:MM: Timezone offset

Examples

Why Use ISO 8601?

• Unambiguous: No confusion between MM/DD and DD/MM
• Sortable: Alphabetical sort = chronological sort
• Includes timezone: Clear what timezone is meant
• Human-readable: Easy to understand at a glance
• Widely supported: Most programming languages parse it natively

RFC 2822 Format

RFC 2822 is the standard format for email headers and HTTP headers. It's more verbose but human-friendly.

Format Structure

Day, DD Mon YYYY HH:mm:ss ±HHMM

Examples

Format Comparison

Best Practices for Developers

1. Store in UTC

Always store timestamps in UTC in your database. Convert to local time only when displaying to users.

// Good: Store UTC
db.save({ created_at: new Date().toISOString() });

// Display: Convert to user's timezone
display(dayjs(record.created_at).tz(userTimezone));

2. Use ISO 8601 for APIs

When building APIs, use ISO 8601 format for all date fields. It's the de facto standard.

{
  "created_at": "2024-01-31T12:00:00Z",
  "updated_at": "2024-01-31T14:30:00Z"
}

3. Be Explicit About Timezones

Never store or transmit dates without timezone information unless you're 100% certain both systems assume UTC.

4. Use Unix Timestamps for Calculations

When doing date math (adding days, comparing dates), Unix timestamps are easiest to work with.

// Add 24 hours
const tomorrow = currentTimestamp + (24 * 60 * 60);

// Check if expired
const isExpired = Date.now() / 1000 > expiryTimestamp;

5. Validate Input Timestamps

Always validate timestamps from user input or external sources. Invalid dates can cause crashes or security issues.

Common Issues and Solutions

The Year 2038 Problem

32-bit systems store Unix timestamps as signed 32-bit integers, which will overflow on January 19, 2038 at 03:14:07 UTC. Solution: Use 64-bit timestamps.

Timezone Confusion

A timestamp like 2024-01-31 12:00:00 without timezone info is ambiguous. Always include timezone or assume UTC.

Daylight Saving Time

Some times don't exist (spring forward) or exist twice (fall back). Use a proper timezone library like dayjs/timezone or moment-timezone.

Milliseconds vs Seconds

JavaScript's Date.now() returns milliseconds, while Unix time() returns seconds. Always check which you're working with.

Programming Examples

JavaScript

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

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

// Parse Unix timestamp
new Date(1706745600 * 1000);

// To ISO 8601
new Date().toISOString();

// Using dayjs
dayjs().unix();  // seconds
dayjs.unix(1706745600).format('YYYY-MM-DD HH:mm:ss');

Python

import time
from datetime import datetime

# Current Unix timestamp
int(time.time())

# Parse Unix timestamp
datetime.fromtimestamp(1706745600)

# To ISO 8601
datetime.now().isoformat()

# Parse ISO 8601
datetime.fromisoformat('2024-01-31T12:00:00+00:00')

PHP

// Current Unix timestamp
time();

// Parse Unix timestamp
date('Y-m-d H:i:s', 1706745600);

// To ISO 8601
date('c');

// Parse any format
strtotime('2024-01-31T12:00:00Z');

Go

import "time"

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

// Parse Unix timestamp
time.Unix(1706745600, 0)

// To ISO 8601 (RFC3339)
time.Now().Format(time.RFC3339)