# Day of the Week Calculator

> Returns the weekday of any Gregorian date together with its day-of-year number, the ISO 8601 week number and week-based year, and whether it falls on a weekend.

- Calculator id: `day-of-week` · Category: Everyday Life (`everyday`) · Tool name: `calculate_day_of_week`
- Canonical page: https://tttkmbb.com/everyday/day-of-week · This document: https://tttkmbb.com/everyday/day-of-week.md · JSON definition: https://tttkmbb.com/everyday/day-of-week.json

## Purpose

Returns the weekday of any Gregorian date together with its day-of-year number, the ISO 8601 week number and week-based year, and whether it falls on a weekend.

**Use when:** You need to know what weekday a date falls on, its ISO week number, or its ordinal day in the year.

**Do not use when:** You need to count days between dates (use date-difference) or determine leap years (use leap-year).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | date |  | optional, default "today" | Any date in the proleptic Gregorian calendar (YYYY-MM-DD); defaults to the current UTC date. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `weekday` | string |  | Day of the week. |
| `day_of_year` | integer |  | Ordinal day number, 1 January = 1. |
| `days_remaining_in_year` | integer | days | Days after this date until 31 December. |
| `iso_week` | integer |  | ISO 8601 week number (1–53); weeks start on Monday and week 1 contains the year's first Thursday. |
| `iso_week_year` | integer |  | Year the ISO week belongs to (can differ from the calendar year around New Year). |
| `iso_week_date` | string |  | Date in ISO week-date notation YYYY-Www-D (D: 1 = Monday … 7 = Sunday). |
| `is_weekend` | boolean |  | true for Saturday or Sunday. |
| `days_in_year` | integer |  | 365 or 366. |

## Formula

`day_of_year = date − 1 January + 1; ISO week: take the Thursday of the same Monday-based week, iso_week = floor((day_of_year(Thursday) − 1) / 7) + 1 and iso_week_year = year of that Thursday`

## Data Sources

- ISO week date (Wikipedia) — https://en.wikipedia.org/wiki/ISO_week_date (reference, retrieved 2026-09-23)
- ISO 8601 – Date and time format (Wikipedia) — https://en.wikipedia.org/wiki/ISO_8601 (reference, retrieved 2026-09-23)

Data freshness: `daily` (max_age_seconds 86400). Depends on the current date unless the date is supplied.

## API

- `GET https://tttkmbb.com/api/v1/calculate/day-of-week?`
- `POST https://tttkmbb.com/api/v1/calculate/day-of-week` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/day-of-week · OpenAPI operationId `calculate_day_of_week` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "day-of-week", "inputs": {…}}`

## Example

- 2026-09-23: inputs `{"date":"2026-09-23"}` → `{"weekday":"Wednesday","day_of_year":266,"days_remaining_in_year":99,"iso_week":39,"iso_week_year":2026,"iso_week_date":"2026-W39-3","is_weekend":false,"days_in_year":365}`
- 2021-01-01 (belongs to ISO week 53 of 2020): inputs `{"date":"2021-01-01"}` → `{"weekday":"Friday","day_of_year":1,"days_remaining_in_year":364,"iso_week":53,"iso_week_year":2020,"iso_week_date":"2020-W53-5","is_weekend":false}`

```
GET https://tttkmbb.com/api/v1/calculate/day-of-week?date=2026-09-23
```

## Limitations

You need to count days between dates (use date-difference) or determine leap years (use leap-year). All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why can the ISO week year differ from the calendar year?**

ISO weeks run Monday–Sunday and week 1 is the week containing the first Thursday of January, so 29–31 December can belong to week 1 of the next year and 1–3 January to week 52/53 of the previous year.

**Are US-style week numbers (weeks starting Sunday) supported?**

No. Only the ISO 8601 definition is returned; US calendars that start weeks on Sunday and call 1 January week 1 can differ by one.

## Related

- [Date Difference Calculator](https://tttkmbb.com/everyday/date-difference.md) — Days and business days between two dates.
- [Leap Year Calculator](https://tttkmbb.com/everyday/leap-year.md) — Check whether the year has 366 days.