Working with Timestamps: A Complete Guide

A UNIX timestamp is the number of seconds (or milliseconds) that have elapsed since January 1, 1970, at 00:00:00 UTC — a moment we call the "UNIX epoch."

Seconds: `1718800000`

Milliseconds: `1718800000000`

Why that date specifically? It was just a convenient convention chosen by early UNIX developers. There's nothing magical about it. The first UNIX manuals just said "Time since epoch", and that epoch got set to that date.

To humans, it's just an ugly number. But to computers? It's beautiful. Just a number! No time zones, no daylight saving time, no formatting confusion, no calendar changes — just a simple count that ticks upwards one second at a time (or millisecond, depending on your system).

This is how almost all computers store time internally, under the hood. JavaScript Date objects use it, Python uses it, databases use it, servers use it — everyone uses UNIX timestamps internally.

Let me put this in perspective: 1 billion seconds was 2001-09-09. We passed that milestone. 2 billion seconds will be 2033-05-18 — that's the year 2038 problem you might have heard about!

Here's the #1 mistake I see with timestamps, and I've made it so many times myself: Confusing seconds and milliseconds.

**My rule of thumb:** Count the digits!

- 10 digits: seconds (good until ~2033, when we hit 2 billion)

- 13 digits: milliseconds

- 16 digits: microseconds (rare, mainly seen in databases or precise systems)

- 19 digits: nanoseconds (very rare)

If you multiply a second timestamp by 1000, you get milliseconds. Divide by 1000 to go the other way. Simple, but so easy to forget.

I once spent hours debugging why dates were appearing as 50,000 years in the future — I had passed a millisecond timestamp to a function expecting seconds! Another time, dates were all appearing in 1970 because I divided when I shouldn't have.

This mistake is so common that most tools will auto-detect and handle it for you — our Timestamp Converter certainly does! You can paste either format and it will figure it out.

One pro tip: When APIs document timestamps, they almost always say something like "UNIX timestamp in milliseconds" or "seconds since epoch" — read the docs carefully!

ISO 8601 is an international standard for representing dates and times. I wish I could go back in time and tell my younger self to just use ISO 8601 for everything — it would have saved me so many bugs.

Here's what it looks like:

`2024-06-20T12:34:56Z`

`2024-06-20T12:34:56+02:00`

Breaking it down piece by piece:

- `YYYY-MM-DD` — Year, month, day (always in that order, no ambiguity! No more confusing March 5 with May 3.)

- `T` — Just a separator between date and time. It could be a space, but T is the standard.

- `HH:MM:SS` — Hour, minute, second (24-hour format, no AM/PM confusion)

- `Z` or offset — `Z` means UTC (think "Zulu"), or you can have an offset like +02:00 or -08:00.

Every modern system can parse ISO 8601. APIs love it, databases love it, frontends love it, and it's human-readable enough.

The best part? It sorts lexicographically. If you have ISO 8601 strings in a list, sorting them gives you chronological order automatically. That's one of those small quality-of-life things that makes a big difference.

Here's the truth: Time zones are hard. Really, really hard. I've been debugging time zone issues for 15 years, and I still encounter new ones.

Let me share some hard-won rules I live by:

1. **Store times in UTC** — Always. No exceptions. If you don't, you will have bugs. I once had a bug where times were off by exactly 1 hour for half the year because we stored times in local time and daylight saving time changed.

2. **Convert to local time only for display** — Keep the internal representation in UTC, convert at the last possible moment when showing to a user. Frontend should handle local time rendering, backend should deal only in UTC.

3. **Be careful with "today"** — "Today" depends on where you are. It's 8 PM in California, but already 11 AM tomorrow in Tokyo. If you ask for "today's orders", you need to specify whose today!

4. **Use a library** — Don't roll your own time zone handling. Just don't. Use date-fns, luxon, day.js, or similar. The edge cases are endless.

Daylight saving time is its own special kind of pain. Some places have it, some don't. Those that do change dates change. The rules change! Libraries handle this for you, and they update their data when laws change.

The only reliable way to handle time is to think in UTC, store in UTC, and only convert when absolutely necessary for display. Our Timestamp Converter shows you both UTC and local time so you can see the difference!

After years of messing this up, here's what works for me with times in APIs:

**What to accept:** ISO 8601 or UNIX timestamps. Give clients a choice, but prefer ISO 8601 because it's self-documenting.

**What to store:** UTC, either as a timestamp (your choice of seconds or milliseconds, just be consistent!) or ISO 8601 with Z. I usually pick milliseconds in PostgreSQL, it works well.

**What to return:** ISO 8601 with explicit timezone info — always. Make it obvious that it's UTC, include the Z.

**What to never do:** Store times as strings in local formats. You will regret it. I've seen CSV exports that have dates like "06/07/2024" and it's impossible to know if that's June 7 or July 6.

When in doubt, just use UTC everywhere and convert only when showing to a human. It's a simple rule and it's saved me countless hours of debugging.

One last tip: When dealing with recurring events (like "every Monday at 9 AM"), time zones get even more complicated. For those, you might need to store the time zone separately, but that's a whole other topic!

Let's look at actual code for working with times. These are snippets I have in my notes app that I reuse all the time.

**JavaScript (Browser or Node):**

// Current timestamp in milliseconds
const nowMs = Date.now();
console.log(nowMs);

// Convert milliseconds to Date object
const date = new Date(nowMs);
console.log(date.toISOString());

// Convert ISO string to Date
const fromIso = new Date('2024-06-20T12:34:56Z');
console.log(fromIso.getTime());

**Python:**

from datetime import datetime, timezone
# Current timestamp in seconds
now = datetime.now(timezone.utc)
print(now.timestamp())
# From timestamp to datetime
date = datetime.fromtimestamp(1718800000, timezone.utc)
print(date.isoformat())

**PostgreSQL:**

-- Current time
SELECT NOW();
-- Get timestamp from column
SELECT EXTRACT(EPOCH FROM created_at) * 1000 FROM users;

I can't stress this enough: When learning a new language or framework, learn how to properly handle dates and times early. It will save you headaches later.

And remember: Use our Timestamp Converter when you just need a quick conversion without writing code!