Method & assumptions

A week number needs its own week-year.

Weekstamp converts one civil date between a Gregorian calendar label and an ISO week-date label. These labels identify the same day using different components. The converter is date-only: it does not choose a timezone, read a device clock, calculate a timestamp or schedule an event.

Two labels for the same day

A Gregorian calendar label has year, month and day, such as 2021-01-01. An ISO week-date label has week-year, week number and weekday, such as 2020-W53-5. In this example both labels identify Friday, 1 January 2021. The ISO week-year is 2020 because the week’s Thursday is 31 December 2020.

Use Calendar date → ISO week date when you have a normal date and need a weekly label. Use the reverse direction when you have a full ISO week date and need its calendar day. Both directions require a complete day, not just a week number.

The ISO week rules used here

• A week starts on Monday and ends on Sunday.
• Weekdays are Monday 1, Tuesday 2, through Sunday 7.
• Week 1 contains the first Thursday of the Gregorian year. Equivalently, it contains January 4.
• An ISO week-year contains 52 or 53 full weeks. Some early-January days belong to the previous ISO year, and some late-December days belong to the next.

A label such as 2020-W53 must keep its week-year. Replacing that year with a day’s Gregorian calendar year can point to a different week or an invalid label. This tool does not implement Sunday-start, week-zero, fiscal, school or custom business-week numbering.

The proleptic Gregorian calendar

Gregorian leap years are divisible by 4, except century years must also be divisible by 400. Thus 2000 has 29 February and 1900 does not. The model applies these rules throughout years 0001–9999, without a country-specific historical calendar cutover. That mathematical convention is not an assertion about which civil calendar a place used in an earlier century.

Integer day arithmetic

The calculation assigns ordinal 1 to 0001-01-01 and counts civil days. It uses safe integer arithmetic rather than a browser date parser or timestamp. No time of day or timezone can shift a result across a date boundary.

ISO weekday = ((ordinal − 1) mod 7) + 1
Thursday of this week = ordinal + 4 − weekday

The Gregorian year containing that Thursday is the ISO week-year. The Thursday’s position within that year determines the week number. For reverse conversion, find the Monday of the week containing January 4, add seven days for each completed ISO week, then add weekday minus one. Week 53 is accepted only if that ISO year actually has 53 weeks.

Accepted input forms

Calendar input must be YYYY-MM-DD: four year digits, two month digits, two day digits and ASCII hyphens. ISO week input must be YYYY-Www-D: four week-year digits, uppercase W, two week digits and one weekday digit from 1 through 7. These intentionally narrow forms avoid ambiguous locale parsing.

Year 0000, signed or expanded years, shortened forms, timestamps, timezone suffixes, slashes, lowercase w, tabs and trailing text are rejected. Optional ASCII spaces are allowed around the full label. Each raw field may contain at most 32 characters, including those spaces. A well-shaped string must still name a real date or valid ISO week.

The supported Gregorian range is 0001-01-01 through 9999-12-31. ISO week-year inputs also use 0001 through 9999, but their decoded Gregorian day must fit the supported Gregorian range. An out-of-range decoded day is a range error, not a silently normalized or clipped date.

Week endpoints at the range boundary

The result shows the Gregorian Monday and Sunday of the identified week when each endpoint is supported. For 9999-12-31, the date itself is valid and its ISO label is 9999-W52-5. Its Monday is 9999-12-27, but the Sunday lies in year 10000. The result remains valid while Sunday is shown as unavailable and exported as null with a reason.

Entering 9999-W52-7 in reverse is different: that full day decodes beyond the supported Gregorian range, so conversion is rejected. The tool does not mislabel it as an invalid week 53, fabricate an expanded-year date or substitute 9999-12-31.

Editing, reset and local exports

The visible examples are fixed values, not a claim about today. Startup and Reset example explicitly restore both example strings and the calendar-to-week direction. Switching direction shows its corresponding field and clears old output. Previously typed field values may remain available when you switch back; there is no automatic conversion until you select Convert date label.

Every edit invalidates old labels, week endpoints and exports. Copy and text/JSON downloads use only the current completed conversion. An unavailable week endpoint remains null in JSON. A late clipboard response cannot restore an old result in the page, although the page cannot revoke text already written to a device clipboard.

Primary model references

• Python’s official datetime documentation describes ISO week components, Monday-first weeks, the first-Thursday rule, inverse conversion and proleptic Gregorian date bounds.
• CPython’s official date reference implementation documents the Gregorian leap-year and ordinal context used for independent checks.

The strict accepted spelling and unavailable-endpoint policy are this calculator’s choices. This is not a universal parser for every date representation. The worked examples show the common year-boundary traps.