ISO 8601 formats: calendar, week, ordinal, and epoch
Published: 2026-09-05
How calendar dates, week dates, ordinal days, and Unix epoch relate in ISO 8601, plus Z vs offsets, basic vs extended forms, and what LocalTools parses locally.
ISO 8601 is the common language for machine-readable dates and datetimes: 2024-01-15, 2024-01-15T10:30:00Z, 2024-W03-1, 2024-032. APIs, logs, and databases all speak dialects of it. Mixing those dialects—or assuming every “ISO string” is a full UTC instant—causes silent off-by-one and timezone bugs.
LocalTools’ ISO 8601 parser breaks a paste into format kind, field components, normalized UTC ISO, and Unix epoch (seconds and milliseconds)—computed only in your browser (local-only).
Calendar dates and date-times
The calendar forms most people mean by “ISO date”:
| Form | Example | Meaning |
|---|---|---|
| Date only | 2024-01-15 |
Year-month-day (no clock) |
Date-time + Z |
2024-01-15T10:30:00.123Z |
Instant in UTC |
| Date-time + offset | 2024-06-01T12:00:00+02:00 |
Instant with fixed UTC offset |
| Year-month / year | 2024-01, 2024 |
Partial calendar (less common on the wire) |
Extended forms use hyphens and a T between date and time (YYYY-MM-DDThh:mm:ss). Basic forms drop separators (20240115, 20240115T103000Z). Same instant; different compactness. Prefer extended in docs and APIs humans read.
Date-only strings are not a full instant until you pick a zone and a clock time. In the parser, date-only (and week/ordinal day) values map to UTC midnight for epoch output so you get a definite number—document that choice in your own APIs rather than relying on Date.parse quirks.
Week dates (YYYY-Www-D)
ISO week dates count weeks of the year, not months:
2024-W03-1→ ISO week 3, weekday 1 (Monday) of the ISO week-year 2024- Weekday runs Mon=1 … Sun=7 (not Sunday-first)
Week 1 is the week that contains the year’s first Thursday (equivalently: the week of January 4). Near year boundaries, the ISO week-year can differ from the Gregorian calendar year—e.g. 30 Dec might still be week 1 of the next week-year.
Use week dates for retail calendars, “ISO week of year” reports, and systems that already speak week numbers. Convert to a calendar day before comparing to civil month/day deadlines.
Ordinal dates (YYYY-DDD)
An ordinal date is day-of-year: 2024-032 is the 32nd day of 2024 (1 February in a non-leap year). Range is 001–365 (or 366 in leap years). Handy in science logs and some aviation formats; rare in consumer APIs.
Like week dates, ordinals resolve to one calendar day; the parser exposes both the ordinal field and the implied year/month/day for epoch.
Epoch: the same instant as a number
Once you have an instant (date-time with Z or a numeric offset, or a date-only mapped to UTC midnight), you can express it as a Unix timestamp:
| Scale | Typical digits (2020s) | Common in |
|---|---|---|
| Seconds | ~10 | JWT exp, many SQL epoch extracts |
| Milliseconds | ~13 | Date.now(), browser Date internals |
ISO strings and epoch integers are two views of one timeline point. Prefer ISO (with explicit Z or offset) in human-facing payloads; use epoch when you need compact numeric sorting or math. Never treat a bare calendar date as interchangeable with an epoch without stating the midnight/zone rule.
Offsets, Z, and “unspecified”
| Marker | Meaning |
|---|---|
Z |
UTC (offset zero) |
+02:00 / -05:30 |
Fixed offset from UTC for that string |
| No zone on a date-time | Ambiguous; browsers may treat as local—prefer explicit Z or offset |
A fixed offset is not an IANA timezone. +02:00 does not know about DST transitions; Europe/Berlin does. Store instants (UTC/Z or epoch); project to IANA zones only for display.
Practical workflow
- Paste the string into the ISO 8601 parser (or click an example: date, offset datetime, week, ordinal).
- Check Format (calendar, week, ordinal, basic, …) and whether parse used a strict ISO match or a
Date.parsefallback. - Copy Normalized UTC (ISO 8601) for logs; copy Unix seconds or ms for APIs that want numbers.
- For multi-city wall clocks from that instant, use the Timezone converter.
- For spans between two datetimes, see exact vs calendar duration.
Prefer strict extended ISO with Z or an explicit offset whenever you control the format. Treat date-only, week, and ordinal inputs as “day identity” unless your contract defines a clock and zone.
Related tools on LocalTools
- ISO 8601 parser — components, UTC normalize, epoch copy
- Unix timestamp converter — seconds vs milliseconds ↔ readable time
- Timezone converter — same instant across IANA zones
- Date difference calculator — exact and calendar spans