Unix timestamps, units, and time-zone mistakes

Identify seconds or milliseconds first

A timestamp around 1,800,000,000 is plausibly seconds for a date in the late 2020s; a value around 1,800,000,000,000 is plausibly milliseconds. These are useful clues, not a guarantee, because older dates, custom counters, and microsecond timestamps use different ranges. Check the API documentation, database type, or a known event before converting. If a program interprets milliseconds as seconds, the result can jump tens of thousands of years into the future.

Name the unit in variable names and interface labels whenever you control the data. `createdAtSeconds` is clearer than `createdAt`, and an API field should document whether it counts seconds, milliseconds, or another unit. Avoid guessing based only on digit count in production code. A value from 1970 or an implausibly distant year is a prompt to inspect units and parsing rules, not a reason to adjust the number until the display looks familiar.

Separate the instant from its displayed time

A timestamp identifies an instant; a time zone determines how that instant is shown on a calendar and clock. The same instant can be 14:00 UTC, 10:00 in New York during daylight time, or 23:00 in Tokyo. Those displays differ without changing the event. When sending a meeting time to another person, include a zone such as UTC or an offset, or use a calendar invitation that carries zone rules.

A date-time string without an offset can be ambiguous. `2026-11-05 09:00` might mean a local office time, UTC, or another region's wall clock. Daylight-saving changes make this especially tricky: a local clock hour can be skipped in spring or occur twice in autumn. Store an unambiguous instant when the event is already determined, and retain the intended time zone for future recurring events such as '9 a.m. every Monday in Chicago'.

Convert carefully and verify a known date

Use a converter that states the expected unit and displays the resulting zone. Enter a known timestamp from a log or an API, then compare it with a trusted event record. Check both the date and the clock time; a mistaken unit can shift the year, while a mistaken zone can shift the day near midnight. If converting in code, use the runtime's documented date constructor and avoid relying on locale-dependent parsing of informal date strings.

When producing a timestamp from a date, decide whether the source is a local time or a UTC time before converting it. For example, entering 9:30 on a calendar without specifying the city does not define one unique instant. A good test includes a date near a daylight-saving transition and a date in winter, because the offset may differ. Store test expectations in UTC or another explicit zone so they remain stable on machines configured in different regions.

Watch boundaries, fractional values, and precision

Events close to midnight can fall on different calendar dates when displayed in another zone. A support ticket created at 00:20 UTC might still belong to the previous local date for a team in California. Decide which zone defines daily reports and billing boundaries, then apply it consistently. Do not change the stored instant just to make a local date match; change the presentation or aggregation rule instead.

Some data sources include fractional seconds, while others round to whole seconds or milliseconds. Preserve the precision required by the task, but do not invent precision that the source never recorded. For log correlation, a difference of 350 milliseconds can matter; for a monthly report, it usually does not. When comparing values, consider whether the system truncates, rounds, or stores higher precision than the display shows, and document the chosen tolerance.

Treat recurring schedules differently from timestamps

A one-time event can be represented as an instant. A recurring instruction such as 'open at 8 a.m. local time every weekday' is a rule tied to a region's civil clock. Saving only the first converted timestamp loses the intent when daylight-saving rules change. Store the recurrence rule and a named time zone, then calculate each occurrence with a time-zone-aware library. This distinction prevents a store from unexpectedly opening at 7 a.m. after a seasonal clock change.

Schedules also need an answer for dates that do not exist or happen twice locally. A rule for 2:30 a.m. may hit a skipped hour in spring, while 1:30 a.m. can occur twice in autumn in some regions. The application should state whether it skips, shifts, or selects one occurrence. A timestamp converter helps inspect specific instants, but business rules for recurring events belong in the scheduling design, not in an improvised manual adjustment.

Make timestamp data understandable to people

For operational notes, include the original numeric value, its unit, and the displayed zone when the exact conversion matters. A message such as 'event at 1793888400 seconds (2026-11-05 09:00 UTC)' is more reproducible than 'it happened at 9'. For customer-facing copy, display local time in a way the audience expects and provide a zone or location where a booking crosses regions. The best format depends on the reader's task.

Before changing stored data, keep the source value and record the conversion rule. A bulk migration that multiplies every value by 1,000 can be wrong if a column already mixes units or includes sentinel values. Sample rows from different dates, compare them with trusted records, and test the conversion on a copy. Conversion is simple arithmetic after the unit and semantics are known; discovering those semantics is the part that deserves care.

Worked examples

A log contains 1,798,000,000 and a converter treats it as milliseconds, showing a date near January 1970.

Interpreting the value as seconds yields a plausible date in 2026; confirm that the log field is documented in seconds.

A launch is set for 09:00 on November 5 in London, and a teammate in Tokyo needs the same instant.

Share the London zone or a UTC instant along with the local display, then let the teammate view it in Tokyo time.