Dates & Times Data API and MCP
Dates & Times publishes its date maths as a free, read-only API and MCP server. Five endpoints cover age, the difference between two dates (with Monday-to-Friday working days), statutory UK holiday entitlement, the long-weekend maximiser, and the 2026 UK bank holidays. There is no authentication and no PII. The data is licensed CC BY 4.0, the same numbers shown on the calculators, drawn from gov.uk Bank Holidays and the Working Time Regulations.
REST endpoints
All endpoints are GET, return JSON, support CORS, and answer OPTIONS preflight. Responses carry an ETag and edge cache headers. The full machine-readable description is in the OpenAPI 3.1 spec.
| Endpoint | What it returns |
|---|---|
GET /api/age | Exact age in years, months, days and total days lived from a date of birth. https://datesandtimes.co.uk/api/age?dob=1990-05-04 |
GET /api/date-difference | Days, weeks, years, months and Monday-to-Friday working days between two dates. https://datesandtimes.co.uk/api/date-difference?from=2026-01-01&to=2026-12-31 |
GET /api/holiday-entitlement | UK statutory holiday entitlement from daysPerWeek (with optional fullTimeEntitlement) or hours (12.07% method). https://datesandtimes.co.uk/api/holiday-entitlement?daysPerWeek=3&fullTimeEntitlement=28 |
GET /api/long-weekend | Best annual-leave dates to book around the 2026 UK bank holidays. nation = ew | sct | ni. https://datesandtimes.co.uk/api/long-weekend?leaveDays=5&nation=ew |
GET /api/bank-holidays | The 2026 UK bank holidays. Omit nation for all three; or nation = ew | sct | ni. https://datesandtimes.co.uk/api/bank-holidays?nation=sct |
MCP server
The same data is available to AI assistants over the Model Context Protocol at https://datesandtimes.co.uk/mcp (streamable HTTP, JSON-RPC 2.0, read-only). The manifest is at /.well-known/mcp.json. Tools:
calculate_age: Exact age from a date of birth.date_difference: Difference between two dates, with Mon-Fri working days.holiday_entitlement: UK statutory holiday entitlement.long_weekend: Best leave dates around the 2026 UK bank holidays.
The 2026 UK bank holidays are also exposed as MCP resources (datekit://bank-holidays and per-nation variants), so an assistant can read the list directly.
Licence and sources
The data is licensed CC BY 4.0: free to reuse with attribution to Dates & Times. Bank-holiday dates come from gov.uk Bank Holidays; holiday-entitlement rules from GOV.UK and the Working Time Regulations 1998. Figures are general calendar and time information, not legal or employment advice. For the human pages, see the calculators, bank holidays and UK calendar data.
Calculators and Data Desk, Dates & Times
Dates & Times's editorial desk builds and documents the calculators, citing the underlying date maths and the official UK source behind every number. Calendar and time tools are checked against primary UK sources such as the gov.uk Bank Holidays API before publication.
Last reviewed: 12 June 2026