Unix Timestamps Explained: Seconds, Milliseconds, and Time Zones

A Unix timestamp, also known as epoch time or POSIX time, is a single number representing the number of seconds that have passed since 00:00:00 UTC on 1 January 1970, known as the Unix epoch. This number is universally applicable, which is why it is favored by databases, logs, and APIs. However, different systems count time in varying units, and mixing them up can lead to common timestamp bugs.

A quick way to differentiate between seconds and milliseconds is by the length of the number: 10 digits (like 1700000000) typically represent seconds, while 13 digits (like 1700000000000) represent milliseconds. JavaScript's Date.now() and Java's System.currentTimeMillis() return the latter.

Passing the wrong unit can set your data to January 1970 or, conversely, many thousands of years into the future. When coding, remember to multiply the seconds value by 1000 before passing it to JavaScript's Date constructor. Python's datetime library also provides a fromtimestamp() method that takes an optional timezone argument.

A Unix timestamp, being an instant in time and not a calendar date, is time-zone agnostic. It's best practice to store and transmit timestamps in this format or as UTC ISO 8601 strings (like 2023-11-14T22:13:20Z), converting to a viewer's time zone only when displaying the data. Common mistakes include adding 86,400 seconds to assume the next day, storing local time without a time zone offset, and comparing seconds to milliseconds.

When dealing with timestamps, always use UTC internally and 64-bit integers or ISO 8601 strings for storage to avoid the Year 2038 problem, where signed 32-bit Unix time will overflow on 19 January 2038. Using UTC for all calculations and only converting to local time for display ensures accurate time representation across all systems.