How to distinguish Unix timestamp seconds from milliseconds

How seconds and milliseconds differ

A Unix timestamp represents elapsed time from the epoch, 1970-01-01 00:00:00 UTC. The unit used for data exchange is not universal, however. In seconds, 1700000000 represents the same instant as 1700000000000 in milliseconds.

For positive values near the present, seconds are often around 10 digits and milliseconds around 13 digits, so length is a useful clue. It changes for older dates, distant future dates, negative values, fractional seconds, and strings with leading zeros. Do not determine the unit from digit count alone.

An order for determining the unit

Start with the source contract. An API specification, database column definition, variable name such as timestamp_ms, or library documentation that states the unit is stronger evidence than the value's shape.

If the contract is unclear, narrow the possibilities in this order:

1. Look for a description of the source value's type and unit.
2. Convert it once as seconds and once as milliseconds.
3. Compare both results with the expected business period. An order date before a service launched or hundreds of years in the future is usually implausible.
4. Check the interval between neighboring records. Values increasing by 1000 for one-second samples may be milliseconds.
5. If the result is still ambiguous, ask the data provider instead of saving a guess.

A 12-digit value is not invalid merely because of its length. It can represent a distant future date as seconds or a date from the 1970s through roughly 2001 as milliseconds. Judge it against the unit contract and expected date range, not a single digit rule.

Accidental multiplication or division by 1000

JavaScript Date accepts milliseconds, so multiply a seconds value by 1000. Multiplying a value that is already milliseconds sends it far into the future or outside the supported range. Passing seconds directly as milliseconds instead places the result near January 1970.

const seconds = 1700000000;
const milliseconds = 1700000000000;

new Date(seconds * 1000).toISOString();
// expected: "2023-11-14T22:13:20.000Z"

new Date(milliseconds).toISOString();
// expected: "2023-11-14T22:13:20.000Z"

new Date(seconds).toISOString();
// wrong unit: "1970-01-20T16:13:20.000Z"

For fractional seconds, a JavaScript conversion such as 1700000000.123 * 1000 preserves millisecond detail. The App Museum converter only auto-detects integer timestamp inputs, so use this code example to inspect fractional seconds. If the destination accepts only integers, define the required rounding behavior rather than choosing it implicitly.

A checklist for an input value

1. Copy the value and inspect its sign, decimal point, and leading zeros.
2. If the input is an integer, inspect the Unix timestamp converter result. The app infers the unit from length, so treat the displayed unit as a candidate rather than proof.
3. For fractional seconds or the other unit interpretation, use the JavaScript example above: pass the original value as milliseconds, then compare it with the value multiplied by 1000.
4. Check whether the UTC result matches the expected date.
5. If a local display is needed, inspect it separately without confusing it with UTC.
6. Record the confirmed unit in code, a schema, or the API contract.

The App Museum Unix timestamp converter infers seconds or milliseconds from the length of common values. This is a quick inspection clue, not a guarantee of the unit for boundary cases including 12-digit values. Compare its result with the source specification.

References

• ECMAScript Language Specification: Time Values and Time Range
• The Open Group Base Specifications: Seconds Since the Epoch