# ISO Week Number

The week number that doesn't depend on which app you asked.

**Why delegate it:** ISO 8601 week 1 is the week containing the year's first Thursday, not the week containing 1 January, and almost every ad-hoc implementation gets that wrong by dividing day-of-year by seven. Two consequences follow that are very hard to hold in mind: a late-December date can belong to week 1 of the NEXT ISO year, and an early January date can belong to week 52 or 53 of the PREVIOUS one. A year has 53 weeks rather than 52 under a specific rule, not a pattern. Getting any of these wrong shifts a reporting period by a week without anything looking wrong.

Site: https://iso-week.gumballtools.com

## Tools

### `iso_week_run` — Convert between dates and ISO week numbers

Converts calendar dates to ISO 8601 week-numbering dates and back, in either direction, and reports how many weeks an ISO year has.

Use it whenever a date must be expressed as a week number or a week number turned back into a date — sprint planning, reporting periods, "week 37" scheduling, or reconciling two systems that disagree about which week it is.

Do not compute this by dividing day-of-year by seven. Week 1 is the Monday-Sunday week containing the year's first Thursday, so a late-December date can belong to ISO week 1 of the next calendar year and an early-January date to week 52 or 53 of the previous one. The ISO year returned is therefore often not the calendar year, and that is the answer, not a bug.

Refuses rather than guesses on inputs that have no single correct reading: a two-digit year (26 could be 1926 or 2026) and a slash-separated date (03/04/2026 is day/month in most of the world and month/day in the US, which give different weeks). Every refusal says what to send instead.

Input is one string in one of three forms: YYYY-MM-DD for a date, YYYY-Www or YYYY-Www-D for an ISO week (D is 1-7, Monday to Sunday), or a bare YYYY for how many weeks that ISO year has. Calendar dates only — no time of day, no timezone.

Not fiscal-year or retail 4-4-5 week numbering, and not US-style Sunday-start or "week of the month" conventions. Those are different systems that also call themselves week numbers.

Direct endpoint: `https://iso-week.gumballtools.com/api/v1/run`

---

Via the aggregator: `https://gumballtools.com/api/mcp`
Direct: `https://iso-week.gumballtools.com/api/mcp`