Unix timestamps in JavaScript, Python and Go

Name the unit in the contract

A timestamp is a count with a unit and epoch. The same integer means different instants if one service reads seconds and another milliseconds.

Use a fixed UTC example to diagnose the boundary. Do not guess a historical or unusual-length timestamp solely from its digit count.

1704067200 seconds = 1704067200000 milliseconds
Both: 2024-01-01T00:00:00.000Z

JavaScript Date uses milliseconds

The numeric Date constructor accepts milliseconds from the Unix epoch. Multiply Unix seconds by 1000 before using that constructor.

Date.now also returns milliseconds. Name variables with a unit suffix to avoid double multiplying an already converted value.

new Date(1704067200 * 1000).toISOString()
→ "2024-01-01T00:00:00.000Z"

Python and Go expose explicit choices

Python time.time returns seconds, often with a fractional part. Go time.Time exposes Unix for seconds and UnixMilli for milliseconds.

Use UTC-aware conversion in Python when displaying a timestamp. A default local-time display can make a correct numeric conversion appear wrong.

Python: datetime.fromtimestamp(1704067200, timezone.utc)
Go:     time.Unix(1704067200, 0).UTC()

Round only at a documented boundary

Fractional seconds can carry subsecond precision. Converting to integer seconds discards that information, while different rounding rules can differ for negative timestamps.

Round-trip the value with the receiving system’s precision. Preserve the original unit in logs and API documentation rather than relying on an informal convention.