Documentation
Holiday-aware date mapping across years — three endpoints, one resolution engine.
01 / Overview
Conventions
Endpoints
Resolution methods
Every response reports how the comparable date was derived:
The input date falls within a registered holiday’s window. The comparable date preserves the same offset from that holiday’s anchor in the target year.
No holiday claims the date. The comparable date falls on the same ISO week number and day-of-week in the target year.
02 / POST /api/comparable/date
Map a single date
Maps a single calendar date to its holiday-aware comparable date in a target year.
Request body
YYYY-MM-DD — the date to map.
Calendar year to map into (1900–2100).
Override per-holiday window defaults (0–365).
Example
POST /api/comparable/date
{
"date": "2024-11-28",
"targetYear": 2026
}200 OK
{
"inputDate": "2024-11-28",
"targetYear": 2026,
"comparableDate": "2026-11-26",
"method": "holiday-window",
"holiday": {
"id": "thanksgiving",
"name": "Thanksgiving",
"anchorDate": "2024-11-28",
"offset": 0,
"targetAnchorDate": "2026-11-26"
}
}03 / POST /api/comparable/week
Map a business week
Maps a Sun–Sat business week to its comparable week in a target year. Provide any date within the desired week; the engine snaps to the Sunday that opens the week, resolves it (holiday-window or ISO-week fallback), then extends the result +6 days.
Request body
YYYY-MM-DD — any date within the week of interest.
Calendar year to map into (1900–2100).
Override per-holiday window defaults (0–365).
Example
POST /api/comparable/week
{
"weekOf": "2024-11-27",
"targetYear": 2026
}200 OK
{
"inputWeek": {
"startDate": "2024-11-24",
"endDate": "2024-11-30"
},
"targetYear": 2026,
"comparableWeek": {
"startDate": "2026-11-22",
"endDate": "2026-11-28"
},
"method": "iso-week-fallback",
"isoWeek": {
"isoWeekYear": 2024,
"week": 48,
"dayOfWeek": 7
}
}04 / POST /api/comparable/range
Map a date range
Maps a date range to its comparable range in a target year, day by day. Maximum range: 366 days. A per-day breakdown is included automatically for ranges ≤ 14 days; set includeDays: true to force it for longer ranges.
Request body
YYYY-MM-DD.
YYYY-MM-DD — must be on or after startDate.
Calendar year to map into (1900–2100).
Override per-holiday window defaults (0–365).
Force the per-day breakdown in the response. Defaults to auto based on range length.
Example
POST /api/comparable/range
{
"startDate": "2024-11-27",
"endDate": "2024-11-29",
"targetYear": 2026
}200 OK
{
"inputRange": {
"startDate": "2024-11-27",
"endDate": "2024-11-29"
},
"targetYear": 2026,
"comparableRange": {
"startDate": "2026-11-26",
"endDate": "2026-11-28"
},
"days": [
{ "inputDate": "2024-11-27", "...": "..." },
{ "inputDate": "2024-11-28", "...": "..." },
{ "inputDate": "2024-11-29", "...": "..." }
]
}Each entry in days has the same shape as a /date response.
05 / Errors
Errors & validation
Every endpoint returns 400 with the same error shape when a request fails validation:
400 Bad Request
{
"error": "string describing what's wrong"
}Validation rules
Must be valid JSON and a JSON object.
date / weekOf / startDate / endDate must be strings in YYYY-MM-DD format.
Must be an integer between 1900 and 2100.
When present, must be an integer between 0 and 365.
Must be on or after startDate; the range must not exceed 366 days.
06 / Holiday registry
Holiday registry
The 21 US holidays checked against every input date. The closest holiday whose window — the request’s windowDays override, or else that holiday’s own default window — contains the date wins. Otherwise the response falls back to matching the same ISO week number and day-of-week.
| Name | Window | Federal | Type |
|---|---|---|---|
| New Year's Day | ±3 | Yes | fixed |
| MLK Day | ±2 | Yes | floating |
| Valentine's Day | ±2 | — | fixed |
| Presidents' Day | ±2 | Yes | floating |
| St. Patrick's Day | ±2 | — | fixed |
| Easter | ±10 | — | floating |
| Tax Day | ±2 | — | fixed |
| Mother's Day | ±2 | — | floating |
| Memorial Day | ±4 | Yes | floating |
| Father's Day | ±2 | — | floating |
| Juneteenth | ±2 | Yes | fixed |
| Independence Day | ±3 | Yes | fixed |
| Labor Day | ±4 | Yes | floating |
| Columbus Day | ±2 | Yes | floating |
| Halloween | ±2 | — | fixed |
| Veterans Day | ±2 | Yes | fixed |
| Thanksgiving | ±5 | Yes | floating |
| Black Friday | ±2 | — | floating |
| Christmas Eve | ±2 | — | fixed |
| Christmas | ±4 | Yes | fixed |
| New Year's Eve | ±2 | — | fixed |