Week number with custom first day

Use it free in the browser for planning boards and locale-specific schedules, or call the API at $0.002 per successful request when pipelines need the same week label every time.

What a custom-start week number is and what the response contains

You pass date as a strict YYYY-MM-DD string and optional first_weekday as an English name (sunday through saturday) or an integer from zero for Sunday through six for Saturday; when first_weekday is omitted, Monday is assumed. After validation the response echoes the normalized date, civil year, month, and day, the day_of_year ordinal, the weekday of the input as both a lowercase name and a Title Case name plus a zero-based index, the resolved first_weekday and first_weekday_index, how many days the date sits from the start of its week, the week_number from one upward, weeks_in_year as the week number of 31 December under the same start day, a week_1_rule of contains_january_1, leap-year and calendar flags, a method tag, and a short formula string for documentation. There is no timezone conversion and no dependency on “today”: either the inputs form a real calendar day and a legal first weekday, or the request fails with invalid_input. Rejected cases include a missing date, shapes such as 2024/03/15, impossible months, non-leap 29 February, and unknown weekday tokens.

How the date and first weekday are read so results stay 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, month names, and ordinal day-of-year alone are not expanded here. 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. The preferred date field is date, but aliases iso_date, d, value, and calendar are accepted so spreadsheets, query strings, and typed forms can reuse the contract without renaming columns. The first_weekday field accepts names or numeric indices and has aliases week_start, start_day, and first_day; empty or omitted values default to Monday so ISO-style week starts remain one keystroke away without forcing the ISO week-year rule. From the validated triple the engine computes day_of_year by summing month lengths with a February leap adjustment, then weekdays of both the input date and 1 January via Sakamoto’s pure-integer method mapped so Sunday is zero and Saturday is six. The offset of January 1 inside the custom week is (weekday of January 1 minus first_weekday plus seven) modulo seven; the week number is the floor of day_of_year minus one plus that offset, all divided by seven, then plus one. The week number of 31 December under the same start day is returned as weeks_in_year so dashboards can know whether a year runs to 52, 53, or 54 week labels for that configuration. Pair the free browser run on this page with the priced API when you need the identical week label inside an automated pipeline.

Where custom-start week numbers fit in planning, reporting, and software

Analysts building year-over-year dashboards can store week_number together with first_weekday_index so filters remain unambiguous when two regions disagree about when the week begins. 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.