How to count or add business days with holidays using an API
Updated 2026-10-12
Use when an agent must count working days between dates or find the date N working days ahead.
From an MCP client, add https://tanod.dev/mcp and call count_or_add_business_days; its free daily calls are applied automatically, no key or signup.
POST to /v1/date/business-days to count working days between two dates or to add working days to a date, skipping weekends and, optionally, the public holidays of a country (250 countries, from the python-holidays data). Holiday rules are modelled by a library, so confirm with an official source for legal or payroll use.
When to use it, and when not
Use it for delivery estimates, payment due dates and notice periods, where weekends and national holidays matter and the agent has no calendar of its own. Use it instead of looping over dates in a prompt.
If you only need the list of holidays for a year, use /v1/holidays. For repeating schedules use the cron route. The data is rules-based and no official calendar is consulted: lunar, religious and one-off holidays can be estimates or missing for some years.
Request
Only mode and start are required. Other fields apply to one mode.
| Field | Mode | Meaning |
|---|---|---|
mode | both | count or add. |
start | both | Date as YYYY-MM-DD, 1900-01-01 to 2199-12-31. |
end | count | End date, at most 20 years from start. Before start gives a negative count. |
days | add | Integer from -7305 to 7305. Negative subtracts; 0 returns start. |
include_start, include_end | count | Booleans, default true. Both true is Excel NETWORKDAYS; include_end false gives the half-open range of numpy.busday_count. |
weekend | both | Weekday names that are not business days, default ["sat","sun"]; [] for none. |
country, subdivision | both | ISO 3166-1 alpha-2 code and an optional code or name such as CA or California. With a country, dates must lie in 1990-2100. |
curl -s -X POST https://tanod.dev/v1/date/business-days \
-H 'content-type: application/json' -H 'X-Tanod-Free: 1' \
-d '{"mode":"count","start":"2026-12-21","end":"2027-01-08","country":"US"}'{"business_days": 13, "calendar_days": 19, "weekend_days": 4,
"holiday_days": 2,
"holidays_skipped": [{"date": "2026-12-25", "weekday": "Friday", "name": "Christmas Day"},
{"date": "2027-01-01", "weekday": "Friday", "name": "New Year's Day"}]}Response
For count: business_days, calendar_days, weekend_days and holiday_days. For add: date, weekday and calendar_days. Both modes also return counting (the rule applied), start_is_business_day, holidays_skipped (date, weekday, name), weekend, country and subdivision. With a country the reply adds the holiday data's source and a note; holidays_truncated flags a cut-off holiday list.
Semantics
count includes both ends by default. add never counts the start date, like WORKDAY, so adding one business day to Christmas Eve 2026 in the UK lands on 29 December (the spec's example is {"mode":"add","start":"2026-12-24","days":1,"country":"GB"}). Weekends are configurable, for example Friday and Saturday.
Free alternatives exist: OpenWorkdays needs no key but takes your own holiday list. This endpoint brings the holiday data with it.
Errors
A bad date, a range over 20 years, an unknown weekday name, or a field missing for the chosen mode is a 422 before any payment, so it is not charged. An unsupported country or subdivision is a 422 from the worker, also not charged. An unpaid call without X-Tanod-Free: 1, or with invalid input, gets a 402 that quotes the price and says in error what is wrong. Typical latency is under 0.2 s.
Price and free allowance
USD 0.001 per call, paid in USDC on Base, Polygon, Solana, BNB Chain or Arbitrum with x402. 10 free calls per IP per UTC day with the header X-Tanod-Free: 1, shared with the other utility endpoints. MCP tool: count_or_add_business_days at https://tanod.dev/mcp (also on /mcp/util), where the free tier is automatic.
Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/util?via=business-days-api as a custom connector (steps), then ask in plain words, for example "What date is 10 working days after 1 March 2026?" The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.
Related guides: Public holidays API, Cron next run API. Back to tanod.dev or the guide index.