ISO Week Number API: Get Week Number for Any Date

Need to determine which week of the year a date falls in? This guide covers ISO week numbering and how to use an API to get accurate week numbers for any date, following the international ISO 8601 standard.

What is ISO Week Numbering?

ISO week numbering is an international standard (ISO 8601) for numbering weeks within a year. Each year has either 52 or 53 weeks, and the first week of the year is the one containing the first Thursday of January.

This system ensures consistency in week-based reporting and scheduling across different countries and systems.

ISO 8601 Week Rules

ISO week numbering follows these rules:

• Weeks start on Monday (not Sunday)
• Week 1 is the week containing the first Thursday of January
• Equivalently: Week 1 is the first week with a majority (4+ days) in January
• December 29-31 may be in week 1 of the next year
• January 1-3 may be in week 52 or 53 of the previous year

Using the Week Number API

TinyFn provides a simple endpoint to get the ISO week number:

GET https://api.tinyfn.io/v1/time/week-number
Headers: X-API-Key: your-api-key

{
  "date": "2024-01-15T00:00:00.000Z",
  "iso_week": 3,
  "iso_year": 2024,
  "iso_week_year": "2024-W03",
  "day_of_week": 1,
  "day_name": "Monday"
}

Parameters

Response Fields

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/time/week-number?' + new URLSearchParams({
    date: '2024-01-15'
  }),
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const result = await response.json();
console.log(result.iso_week); // 3
console.log(result.iso_week_year); // "2024-W03"

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/time/week-number',
    params={'date': '2023-01-01'},
    headers={'X-API-Key': 'your-api-key'}
)
result = response.json()
print(result['iso_week'])  # 52 (belongs to 2022!)
print(result['iso_year'])  # 2022

cURL

curl "https://api.tinyfn.io/v1/time/week-number?date=2024-12-31" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Weekly Reports: Group data by ISO week for consistent reporting
• Payroll: Calculate pay periods based on ISO weeks
• Sprint Planning: Align sprints with ISO weeks
• Manufacturing: Track production by week number
• File Naming: Use week numbers in file/folder names

Best Practices

1. Use ISO year, not calendar year: At year boundaries, the ISO year may differ from the calendar year
2. Display clearly: Use the "YYYY-Www" format (e.g., 2024-W03) for clarity
3. Be consistent: Stick to either ISO weeks or US weeks (Sunday start) throughout your system
4. Handle week 53: Some years have 53 weeks; plan for this in your logic