# Date Difference Calculator

> Counts the days between two ISO dates and expresses the gap as weeks and days, as a calendar breakdown in years, months and days, and as business days (Monday–Friday, public holidays not excluded).

- Calculator id: `date-difference` · Category: Everyday Life (`everyday`) · Tool name: `calculate_date_difference`
- Canonical page: https://tttkmbb.com/everyday/date-difference · This document: https://tttkmbb.com/everyday/date-difference.md · JSON definition: https://tttkmbb.com/everyday/date-difference.json

## Purpose

Counts the days between two ISO dates and expresses the gap as weeks and days, as a calendar breakdown in years, months and days, and as business days (Monday–Friday, public holidays not excluded).

**Use when:** You need the number of days, weeks or working days between two dates, or a calendar-style 'x years y months z days' difference.

**Do not use when:** You want to add or subtract a number of days from a date (use add-days), or you need an age with the next birthday (use age).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `start_date` | date |  | required | First date (ISO 8601, YYYY-MM-DD). |
| `end_date` | date |  | required | Second date (YYYY-MM-DD). If it is earlier than start_date the dates are swapped and a note is returned. |
| `include_end_date` | boolean |  | optional, default false | true counts both endpoints (adds one day to days, weeks/days and business_days), e.g. for inclusive rental or leave periods. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `days` | integer | days | end_date − start_date in days (+1 when include_end_date is true). |
| `weeks` | integer | weeks | floor(days / 7). |
| `remaining_days` | integer | days | days − 7 × weeks. |
| `weeks_and_days` | string |  | Same gap written as weeks and days. |
| `calendar_years` | integer |  | Whole years between the two dates (not affected by include_end_date). |
| `calendar_months` | integer |  | Whole months beyond the years. |
| `calendar_days` | integer |  | Days beyond the whole months. |
| `calendar_text` | string |  | Years, months and days written out (zero parts omitted). |
| `business_days` | integer | days | Mondays to Fridays among the counted days (public holidays are not excluded). |

## Formula

`days = end_date − start_date (+1 if include_end_date); weeks = floor(days / 7); remaining_days = days mod 7; business_days = number of Mon–Fri dates in [start_date, end_date) or [start_date, end_date] when inclusive; calendar breakdown = whole years, months, then days borrowed from the month before end_date`

Counts calendar days in UTC without times of day. By default the count is exclusive of end_date, so Monday to Friday of one week is 4 days and 4 business days; set include_end_date for 5.

## Data Sources

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

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/date-difference?start_date=…&end_date=…`
- `POST https://tttkmbb.com/api/v1/calculate/date-difference` 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/date-difference · OpenAPI operationId `calculate_date_difference` 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: `calculate_date_difference` (dedicated) or `run_calculator` with `{"calculator_id": "date-difference", "inputs": {…}}`

## Example

- 2026-01-01 to 2026-12-25: inputs `{"start_date":"2026-01-01","end_date":"2026-12-25"}` → `{"days":358,"weeks":51,"remaining_days":1,"weeks_and_days":"51 weeks 1 day","calendar_years":0,"calendar_months":11,"calendar_days":24,"calendar_text":"11 months 24 days","business_days":256}`
- 2025-11-05 to 2026-03-15 inclusive: inputs `{"start_date":"2025-11-05","end_date":"2026-03-15","include_end_date":true}` → `{"days":131,"weeks":18,"remaining_days":5,"weeks_and_days":"18 weeks 5 days","calendar_months":4,"calendar_days":10,"calendar_text":"4 months 10 days","business_days":93}`

```
GET https://tttkmbb.com/api/v1/calculate/date-difference?start_date=2026-01-01&end_date=2026-12-25
```

## Limitations

You want to add or subtract a number of days from a date (use add-days), or you need an age with the next birthday (use age). Counts calendar days in UTC without times of day. By default the count is exclusive of end_date, so Monday to Friday of one week is 4 days and 4 business days; set include_end_date for 5. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Does business_days exclude public holidays?**

No. It only excludes Saturdays and Sundays; subtract the holidays of your jurisdiction yourself.

**Why does the calendar breakdown not add up to the day count?**

Months have different lengths, so 'x months y days' is a calendar convention: whole months are counted first and the leftover days are borrowed from the month preceding end_date.

## Related

- [Add or Subtract Days Calculator](https://tttkmbb.com/everyday/add-days.md) — Add or subtract days from a date.
- [Age Calculator](https://tttkmbb.com/everyday/age.md) — Exact age with next-birthday countdown.
- [Days Until Calculator](https://tttkmbb.com/everyday/days-until.md) — Countdown from today to a target date.