Time Formats Reference

Machines and APIs use specific formats to represent time. Understanding these formats prevents silent failures and timezone bugs.

ISO 8601 — The Universal Standard

ISO 8601 is the international standard for date and time representation. Most modern APIs expect this format.

A complete datetime looks like 2024-01-15T14:30:00Z or 2024-01-15T14:30:00-08:00. The T separates date from time. The suffix indicates timezone: Z means UTC (Zulu time), while -08:00 is an offset from UTC. Without a suffix, the time is "local" — ambiguous and dangerous. Always include a timezone indicator.

Date-only format is 2024-01-15 (year-month-day). This is unambiguous for the date itself, but be careful: when APIs convert date-only to datetime, they typically assume midnight — but midnight in WHICH timezone? A date-only value of 2024-01-15 could mean midnight UTC, midnight local time, or midnight in the API's default timezone. When precision matters, use a full datetime.

Time-only format is 14:30:00 or 14:30 (24-hour clock). Rarely used alone since time without date or timezone is ambiguous.

Week dates use 2024-W03 for week 3 of 2024, or 2024-W03-1 for Monday of that week. ISO weeks start on Monday and the first week of the year contains the first Thursday.

RFC 3339 — The Internet Standard

RFC 3339 is a profile of ISO 8601 designed for internet protocols. For practical purposes, treat them as interchangeable — RFC 3339 is slightly stricter (requires T separator, prohibits some ISO 8601 edge cases).

Most JSON APIs and web services use RFC 3339 format: 2024-01-15T14:30:00Z or 2024-01-15T14:30:00.123Z (with milliseconds). JavaScript's new Date().toISOString() produces RFC 3339 format in UTC.

Unix Timestamps — Seconds Since Epoch

Unix timestamps count seconds (or milliseconds) since January 1, 1970 00:00:00 UTC — the "Unix epoch." They're timezone-agnostic by definition since they represent a single instant in time.

Seconds format is a 10-digit number like 1705330200 (around January 2024). Milliseconds format is 13 digits like 1705330200000. APIs vary — JavaScript uses milliseconds (Date.now()), Python's time.time() returns seconds as a float, and many APIs use integer seconds.

Converting: new Date(1705330200 * 1000) in JavaScript (multiply seconds by 1000 for milliseconds). In Python: datetime.fromtimestamp(1705330200).

Timestamps are excellent for storage and comparison since they're unambiguous. They're poor for human display since they require conversion to a readable timezone.

RFC 2822 — Email Dates

RFC 2822 defines the date format used in email headers: Mon, 15 Jan 2024 14:30:00 -0800. This format includes the day name, spelled-out month, and explicit timezone offset.

You'll encounter this format when parsing email headers or working with older HTTP headers. JavaScript's Date constructor can parse it, but for creating dates, prefer ISO 8601.

Duration Formats

ISO 8601 defines duration format: P prefix followed by period designators. P1D means 1 day, PT2H30M means 2 hours 30 minutes (the T separates date parts from time parts). P1Y2M3D means 1 year, 2 months, 3 days.

Durations are different from time differences. A duration of "1 month" added to January 31 yields February 28 (or 29), not "31 days later." This matters for recurring events and subscription billing.

Human-readable durations vary: "2h 30m", "2:30:00", "150 minutes" all mean the same thing. When accepting user input, be flexible in parsing; when outputting, be consistent.

Format Selection Guide

For API requests and responses, use ISO 8601 with explicit timezone: 2024-01-15T14:30:00-08:00 or UTC with Z suffix.

For database storage, use UTC timestamps (either ISO 8601 with Z or Unix epoch). Store the user's timezone preference separately.

For human display, convert to the user's timezone and use locale-appropriate formatting. Never display raw ISO 8601 or Unix timestamps to users.

For date-only values (birthdays, holidays, deadlines), use YYYY-MM-DD format but be explicit about timezone handling when converting to datetime.