ForHosting KIT · Dates & time

US week number calculator

Find the US week number of any date, with weeks running Sunday to Saturday and week 1 holding 1 January: 15 March 2024 falls in week 11. You also see how many weeks the year has, 53 in 2024. Free in your browser.

Free
Runs in your browser
No sign-up
Your data stays on your device

Run — free How it works & API

Use it from WebAPIEmailTelegramApp soon

Worked example

If you enter

Date: 2024-03-15

You get

Year: 2,024
Month: 3
Day: 15
Day of year: 75

In the United States many calendars, payroll systems, school planners, and spreadsheet models number weeks so that each week begins on Sunday and week one is simply the week that contains the first of January. That rule differs from the ISO 8601 week date system, which starts weeks on Monday and defines week one as the week that holds the first Thursday of the year.

US week rules versus ISO weeks, and how to send a date

Under the US convention used here, a week always starts on Sunday and ends on Saturday. Week one of a year is the week that includes January first, even when that week began in December of the previous year on the calendar wall. Later weeks are counted as complete Sunday-through-Saturday blocks until December thirty-first, which may fall in week fifty-two or week fifty-three depending on where January first landed and whether the year is a leap year.

ISO 8601 weeks are different: they start on Monday, and week one is the week with the year's first Thursday, so the same civil day can map to a different week index. Send either a date string in YYYY-MM-DD form, or structured year, month, and day fields together.

How the number is computed and what invalid dates look like

The engine first validates the Gregorian calendar day, applying leap-year rules so February has twenty-nine days only when the year is divisible by four, except that century years must also be divisible by four hundred. The US week number equals the floor of day-of-year minus one plus the weekday of January first, all divided by seven, plus one, where Sunday is weekday zero. That formula places January first in week one and advances by one each subsequent Sunday.

Malformed strings that are not four-digit year, two-digit month, and two-digit day separated by hyphens are likewise rejected.

What you can do with it

Payroll and US work-week reports

HR and payroll pipelines that group hours by Sunday-start weeks label each pay period with the US week number that contains the work date, matching common spreadsheet WEEKNUM expectations.

School and retail planning calendars

District calendars and retail merchandising plans often number weeks with January 1 in week 1; convert ISO dates to that index for slides, email digests, and inventory windows.

FAQ

Is this the same as the ISO week number?

No. ISO weeks start on Monday and define week 1 by the first Thursday rule. The same civil date can yield a different index under ISO rules.

What happens if the date is invalid?

Examples include bad YYYY-MM-DD format, February 30, or February 29 in a non-leap year. Failed validation is not charged.

Is the US week number calculator free?

The browser tool runs free on your device.

Can a year have 53 US weeks?

Yes. 31 December falls in week fifty-two or week 53, depending on the weekday of 1 January and on leap years. In 2024, for example, the last week of the year is week 53.

Can week 1 begin in December?

Yes. Week 1 is the Sunday-to-Saturday week that contains 1 January, so when 1 January falls midweek, that week started in the last days of December of the year before.

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

POSThttps://api.kit.forhosting.com/date/us-week-number

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/us-week-number \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2024-03-15","calendar":"valor-ejemplo"}'

const res = await fetch("https://api.kit.forhosting.com/date/us-week-number", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "date": "2024-03-15",
    "calendar": "valor-ejemplo"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/date/us-week-number",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "date": "2024-03-15",
    "calendar": "valor-ejemplo"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/us-week-number", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"date":"2024-03-15","calendar":"valor-ejemplo"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"date":"2024-03-15","calendar":"valor-ejemplo"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/us-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-03-15",
  "calendar": "valor-ejemplo"
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "date.us_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

Per request$0.002

Published price — no tokens, no invented credits. A failed task is never charged.

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

US week rules versus ISO weeks, and how to send a date

Aliases such as calendar, calendar_date, and iso_date are accepted for the string path. Partial structured input without all three parts is rejected with invalid_input so callers fix the body instead of guessing missing values. Identical inputs always produce identical JSON because the path never reads the wall clock, locale, or network.

How the number is computed and what invalid dates look like

Impossible dates such as April thirty-first, February thirtieth, or February twenty-ninth in a non-leap year fail with invalid_input and a message that states the real length of the month. The response echoes week_starts equal to Sunday, week_1_rule equal to contains_january_1, and weeks_in_year equal to the US week of December thirty-first so dashboards can show year range without a second call.

API usage, pricing, workflows, and practical limits

Call the free in-browser US week number calculator for homework checks, planning demos, and quick verification without installing calendar libraries. Year bounds follow the published parameter range for isolate safety. Send a JSON body with date as YYYY-MM-DD, or with year, month, and day as integers in the published ranges. On success the payload includes the normalized date, structured components, day_of_year, day_of_week from zero for Sunday through six for Saturday with an English name, week_number, weeks_in_year, is_leap_year, calendar equal to gregorian, and method equal to us_week_number for routers and tests that branch on labels. Use the prepaid API when a payroll export, school calendar, retail planning tool, or SDK needs a stable contract under KIT balance at $0.002 per successful item; validation failures never consume balance after the engine rejects the request. Pair this endpoint with ISO ordinal or days-in-month tools when you need day indexes or February length, but do not expect the week index to match ISO week-date labels.

Integration use cases

Spreadsheet parity in APIs

Services that must match Excel or Google Sheets Sunday-based week numbers expose a stable JSON field instead of reimplementing weekday math in every client language.

Technical questions

How do I get the US week number for a date?

Send JSON with date set to an ISO string such as 2024-03-15, or send year, month, and day. The response includes week_number and day_of_week_name.

Do weeks start on Sunday or Monday?

Sunday. This calculator uses the US convention: week_starts is always Sunday, and week 1 is the week that contains January 1.

Read the full KIT documentation →

Run — free

Worked example

US week rules versus ISO weeks, and how to send a date

How the number is computed and what invalid dates look like

What you can do with it

Payroll and US work-week reports

School and retail planning calendars

FAQ

Related tools

For developers — API access

API endpoint

Call it from your stack

Example request

Example response

Pricing

Errors

Technical notes

US week rules versus ISO weeks, and how to send a date

How the number is computed and what invalid dates look like

API usage, pricing, workflows, and practical limits

Integration use cases

Spreadsheet parity in APIs

Technical questions

thank you