guide-category-time

Time tools: timestamps, time zones and dates

Dates look simple until a timestamp is off by a factor of 1,000 or a meeting moves an hour. A few rules prevent most of the trouble.

The tool

The Unix epoch converter turns timestamps into UTC and local dates and back again. It detects whether a value is in seconds or milliseconds from its length, and it always tells you which interpretation it used.

Three rules for fewer date bugs

  1. Store instants in UTC. A Unix timestamp or an ISO 8601 string with a Z or offset identifies a single moment everywhere. Convert to local time only when showing it to a person.
  2. Know your unit. JavaScript's Date.now() returns milliseconds; many server languages and databases use seconds. Name fields so the unit is obvious, such as created_at_ms.
  3. Keep the time zone with future local events. A meeting at “09:00 in Berlin” should be stored with the zone name Europe/Berlin, not just an offset, because offsets change with daylight saving time and law.

Reading timestamps quickly

For dates between 2001 and 2286, a seconds timestamp has 10 digits and a milliseconds timestamp has 13. Values around 16 digits are usually microseconds, and around 19 digits nanoseconds, which some databases and tracing systems use. If a converted date lands in 1970 or thousands of years from now, the unit is almost certainly wrong.

Further reading

Our article Unix timestamps: seconds vs. milliseconds lists how common languages and databases report time, explains the year-2038 problem, and gives a checklist for storing time safely.