ISO week number calculator
Type a date and get its ISO week: 2024-01-01 is week 1 of 2024, while 2021-01-01 still sits in week 53 of 2020. The week-year comes with it, so late December and early January are labeled right. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Date
- 2024-01-01
- Year
- 2,024
- Month
- 1
- Day
- 1
- Iso week
- 1
This ISO week number calculator takes a single Gregorian calendar date in YYYY-MM-DD form and returns its ISO-8601 week number together with the week-numbering year those two values belong to. ISO weeks always start on Monday and end on Sunday, and week 1 of a year is the week that contains that year's first Thursday — which is why late December and early January often report a week-year that differs from the civil year on the calendar. Classic checks include 2024-01-01 mapping to week 1 of 2024, and 2021-01-01 mapping to week 53 of 2020. The engine uses only deterministic integer calendar arithmetic: leap years, month lengths, ordinal day-of-year, and ISO weekday are computed without network calls, random sampling, or the host clock.
What your ISO week number tells you
ISO-8601 week dates answer a different question from month-and-day calendars: they locate a day inside a Monday-based week that is numbered from 1 to 52 or 53 inside a week-numbering year. Week 1 is defined as the week containing the year's first Thursday, which is equivalent to the week that contains 4 January. Because of that rule, 29 December through 3 January can belong to the previous or next week-year even when the civil year on the invoice still says the old or new number.
If you need Unix epochs, multi-format parsing, or business-day arithmetic, use those dedicated tools; this page answers only the ISO week number and week-year for a validated calendar date.
How the date is read and how the week stays reproducible
The string must match four digits, a hyphen, two digits, another hyphen, and two digits; leading or trailing spaces are trimmed, but partial dates, ordinal day-of-year alone, and month names are not expanded here. After parsing, the year must fall between 1 and 9999, the month between 1 and 12, and the day between 1 and the true length of that month in that year, with leap years following the Gregorian rule of divisible by four except century years not divisible by four hundred.
From the validated triple the engine computes the day of year by summing month lengths, the ISO weekday via Sakamoto's pure-integer method mapped so Monday is one and Sunday is seven, then the week number as the floor of day-of-year minus weekday plus ten, all divided by seven. When that week is less than one, the date belongs to the last week of the previous week-year; when it exceeds the number of weeks in the civil year, it belongs to week one of the next week-year.
A year has fifty-three ISO weeks when its first or last day is a Thursday.
Where ISO week numbers fit in planning, reporting, and software
Operations and finance teams use ISO week numbers when a weekly cadence must line up across countries that do not all start the week on Sunday: manufacturing schedules, retail sell-through packs, agile sprint labels, and statutory reporting that cites week-of-year all benefit from a single unambiguous week id. Developers call the same contract from scripts to stamp log buckets, to generate deterministic test vectors for payroll and timesheet systems, or to satisfy product requirements that demand W01 through W53 labels rather than ad-hoc local week numbering.
Educators and standards writers use the tool to demonstrate boundary dates such as 2005-01-01 in week 53 of 2004 versus 2005-01-03 in week 1 of 2005 without relying on spreadsheet serial numbers that differ between Excel and ISO. Pair it with epoch conversion or date normalization when you need related calendar steps, and with other free deterministic helpers when you are assembling a small lab of date utilities.
What you can do with it
Weekly reporting labels
Stamp dashboards, retail packs, and ops reports with stable ISO week and week-year pairs instead of locale-dependent local weeks.
Year-boundary compliance checks
Verify late December and early January dates that belong to the previous or next week-year before closing books or filing week-based stats.
FAQ
What does the ISO week number calculator cost?
It is free in your browser on this page.
How is the ISO week number defined?
Weeks run Monday–Sunday. Week 1 is the week containing the year's first Thursday (the week that contains 4 January). The result may use a week-year different from the civil year.
Does this convert time zones or use the current clock?
No. It only maps a validated calendar date to ISO week fields with pure arithmetic.
Why is January 1, 2021 in week 53 of 2020?
Week 1 of a year is the one that holds its first Thursday, and January 1, 2021 falls in the days before it. That day therefore stays in the last week of 2020, which is week 53.
What else does the result show besides the week number?
You also get the weekday from 1 for Monday to 7 for Sunday with its name, a short label such as 2024-W01, how many weeks that week-year has and the day of the year.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/date/iso-week-number \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"date":"2024-01-01"}'const res = await fetch("https://api.kit.forhosting.com/date/iso-week-number", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"date": "2024-01-01"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/date/iso-week-number",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"date": "2024-01-01"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/iso-week-number", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"date":"2024-01-01"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"date":"2024-01-01"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/iso-week-number", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"date": "2024-01-01"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "date.iso_week_number",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
year_min | 1 |
year_max | 9999 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
Use it free in the browser for planning, payroll, and compliance worksheets, or call the API at $0.002 per successful request when you need reproducible week labels in CI, reporting pipelines, or product features.
What an ISO week number is and what the response contains
This calculator accepts one required field, date, as a strict YYYY-MM-DD string, validates that the day actually exists in the Gregorian calendar — including February 29 only in leap years and the correct length of every month — then returns the normalized date, civil year, month, and day, the ISO week number as iso_week, the week-numbering year as iso_week_year, the ISO weekday from 1 for Monday through 7 for Sunday with a readable name, a compact iso_week_string such as 2020-W53, how many weeks that week-year contains, the day-of-year ordinal, and a short formula reminder. There is no timezone conversion, no locale-dependent first day of week, and no floating approximation: either the input is a real calendar day and the week fields are fully determined, or the request fails with invalid_input. Rejected cases include missing date, wrong shape such as 2024/01/01, impossible months, and days that do not exist such as 2023-02-29.
How the date is read and how the week stays reproducible
The preferred field is date, but aliases iso_date, d, and value are accepted so spreadsheets, query strings, and typed forms can reuse the same contract without renaming columns. Pair the free browser run on this page with the priced API when you need the identical week label inside an automated pipeline.
Where ISO week numbers fit in planning, reporting, and software
Analysts building year-over-year dashboards avoid the classic off-by-one where the first days of January still belong to week 52 or 53 of the prior week-year if they store both iso_week and iso_week_year instead of only the civil year. On this page the work runs entirely in your browser; through the API each successful lookup costs $0.002, failed validation is not charged, and nothing is stored after the response returns. That split — free interactive exploration and a priced, identical API — matches the rest of the KIT tier-A catalog and lets you move from a one-off check to a pipeline without changing the mathematical result.
Integration use cases
Deterministic test fixtures
Generate reproducible iso_week and iso_week_string values for unit tests, property checks, and CI assertions without Date skew.
Technical questions
Why can iso_week_year differ from the calendar year?
Dates from about 29 December through 3 January often fall in the last week of the previous week-year or week 1 of the next one under ISO-8601 rules.
What date formats are accepted?
Only strict YYYY-MM-DD calendar dates. Values like 2024/01/01, 01-01-2024, or 2023-02-29 (non-leap) are rejected with invalid_input.