Month views, day details, date ranges, and holiday lookups with fiscal-year attributes built in. Deterministic output, nothing stored.
This calls the real Calendar API. Switch the endpoint, year, and country, and the response updates with the same parameters you would send yourself.
| date | day_name | iso_week | is_business_day | fiscal_quarter |
|---|---|---|---|---|
| Loading live response... | ||||
Why Calendar API
BI-ready date rows
Every day includes date_key, iso_week, week_of_month, quarter, and business-day flags. Built to drop straight into a PowerBI date dimension.
Fiscal year support
Set fiscal_year_start_month and every row carries fiscal_year, fiscal_quarter, and fiscal_period computed for your company calendar.
Holiday enrichment
Merge public holidays by country with your own custom_holidays list. Responses include per-day holiday counts and a merge summary.
Range queries
Pull up to 366 days in one request with optional weekend filtering, and flat or nested weekly output shapes.
Locale and week control
Choose monday or sunday week starts, localized month and day names, and an IANA timezone echoed in metadata for downstream tools.
Stateless and deterministic
The same query always returns the same structure. No calendars, custom config, or user data are stored on Datpaq servers.
/api/v1/calendar
Month view
Requires year and month. Returns the month calendar structure with BI-friendly date attributes, flat or nested by week.
Single day
Requires date (YYYY-MM-DD). Returns every attribute for one date with optional holidays.
Date range
Requires start_date and end_date, up to 366 days. Optional weekend filtering and nested weeks output.
Holidays
Requires year. Public holidays by country, custom holidays via JSON, or both merged with warnings.
Service health
Status, service name, version, and timestamp for monitoring.
Prometheus metrics
Request counts and latency histograms in Prometheus exposition format.
| Parameter | Type | Required | Description |
|---|---|---|---|
| year | integer | month, holidays | Calendar year for month and holidays endpoints. |
| month | integer | month | Month number from 1 to 12. |
| date | string | day | ISO date (YYYY-MM-DD) for the day endpoint. |
| start_date / end_date | string | range | ISO date window for the range endpoint. end_date must be on or after start_date; max span is 366 days. |
| include_holidays | boolean | no | Enables holiday enrichment on month, day, and range responses. Default false. |
| country_code | string | with public holidays | ISO2 country code, required when the holiday source includes public holidays. |
| custom_holidays | string | no | JSON array of custom holidays (date, name, optional type) merged with or replacing public data via holiday_sources. |
| fiscal_year_start_month | integer | no | Fiscal year start month from 1 to 12. Default 1. Drives fiscal_year, fiscal_quarter, and fiscal_period. |
| week_start | string | no | First day of week: monday or sunday. |
| output_format | string | no | Output shape for month and range: flat (default) or nested weekly rows. |
Error reference
Every error response includes a correlationId and a plain-English error message.
Invalid query values, bad date formats, or malformed custom_holidays JSON. The details array lists each failing field.
end_date is before start_date, or the requested window exceeds the 366-day maximum.
Unknown route. Valid paths are /month, /day, /range, and /holidays under /api/v1/calendar.
More than 120 requests in a 15-minute window. The response includes retryAfter seconds.
Public holiday data was requested but the upstream source is unavailable. Retry or use custom holidays.
Unexpected service failure. Include the correlationId when reporting the issue.
Example error response
{
"success": false,
"error": "Invalid query parameters",
"details": [
"end_date must be greater than or equal to start_date"
],
"correlationId": "4a4a0dc0-52ea-4c9f-89c7-3c0c4c6d4f2a"
}FAQ
Every date row includes a numeric date_key (e.g. 20260704), ISO week and year, quarter, week of month, day names, and business-day flags. The flat output format maps directly onto a star-schema date dimension without transformation.
Yes. Pass a custom_holidays JSON array (date, name, optional type) and set holiday_sources to custom or both. Custom entries merge with public holidays and the response includes a holiday_summary with counts and warnings.
GET /range accepts up to 366 days per request. For longer windows, split the range into consecutive requests; results are deterministic so pages always line up.
No. The service is stateless: it generates calendar structures on demand and stores no calendars, custom holiday lists, or user data on Datpaq servers.
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Month grids, fiscal columns, and holiday-aware business days from one stateless endpoint. No lookup tables to build, no calendar math to maintain.