Free JSON API · No key

Week number API

Get today's ISO week number, or the week for any date, as JSON. Open CORS, no sign-up, cached at the edge.

GET https://weeknumber.io/api/week

Try it: /api/week ?date=2027-01-01

Parameters

Query parameters
Parameter	Format	Description
`date`	YYYY-MM-DD	Return the week for this date. Example: `?date=2026-12-31`
`year + week`	ISO year and week	Return the Monday of that ISO week. Example: `?year=2026&week=53`
`tz`	IANA time zone	Which "today" to use when no date is given. Default `UTC`. Example: `?tz=America/New_York`

Without parameters the API returns the current week in UTC. Invalid input returns HTTP 400 with {"error": "..."}.

Example response

GET /api/week?date=2027-01-01: January 1, 2027 still belongs to ISO week 53 of 2026.

{
  "date": "2027-01-01",
  "timezone": "UTC",
  "isoYear": 2026,
  "isoWeek": 53,
  "isoCode": "2026-W53",
  "weekday": 5,
  "dayName": "Friday",
  "weekStart": "2026-12-28",
  "weekEnd": "2027-01-03",
  "weeksInIsoYear": 53,
  "dayOfYear": 1,
  "daysInYear": 365,
  "usWeek": 1,
  "parity": "odd",
  "url": "https://weeknumber.io/week-numbers/2026/week-53/"
}

GET /api/week?year=2026&week=53

{
  "date": "2026-12-28",
  "timezone": "UTC",
  "isoYear": 2026,
  "isoWeek": 53,
  "isoCode": "2026-W53",
  "weekday": 1,
  "dayName": "Monday",
  "weekStart": "2026-12-28",
  "weekEnd": "2027-01-03",
  "weeksInIsoYear": 53,
  "dayOfYear": 362,
  "daysInYear": 365,
  "usWeek": 53,
  "parity": "odd",
  "url": "https://weeknumber.io/week-numbers/2026/week-53/"
}

Response fields

isoYear, isoWeek, isoCode: ISO 8601 week-numbering year, week (1–53) and code such as 2026-W40
weekday, dayName: ISO weekday, 1 = Monday to 7 = Sunday
weekStart, weekEnd: Monday and Sunday of the ISO week
weeksInIsoYear: 52 or 53
dayOfYear, daysInYear: Ordinal day and 365 or 366
usWeek: US week number: Sunday-start weeks, week 1 contains January 1 (Excel WEEKNUM type 1)
parity: "even" or "odd"
url: Human-readable page for the week

Use it from JavaScript

const res = await fetch("https://weeknumber.io/api/week?tz=Europe/London");
const { isoWeek, isoCode } = await res.json();
console.log(`It's week ${isoWeek} (${isoCode})`);

Or from a terminal: curl -s https://weeknumber.io/api/week

CORS and caching

Every response sends Access-Control-Allow-Origin: *, so you can call it directly from a browser on any site. Responses for "today" are cached for up to one hour and never past midnight in the requested time zone. Responses for a fixed date or week are cached for a day.

Fair use

The API is free for personal and commercial use. Please cache results on your side where you can and avoid more than a few requests per second. A link to Weeknumber.io is appreciated. The service is provided as is, without guarantees; see the terms and the methodology. Want a ready-made widget instead? Use the week number badge.