Business days API reference
Add business days to a date or count them between two dates, using our public holidays.
Request
GET / adds business days to a date, or counts the business days between two dates. A business day is a day that is not a weekend day or a nationwide public holiday of the country. Weekends follow the country: Saturday and Sunday in most, Friday and Saturday in Saudi Arabia, Israel and Bahrain, for example. Use your Narwhal bearer key.
curl --request GET \
--url "https://api.narwhalapi.com/v1/calendars/business-days/USA?from=2026-11-25&add=3" \
--header "Authorization: Bearer $NARWHAL_API_KEY"Parameters
| Name | Type | Rule |
|---|---|---|
country | string | Required path value. ISO 3166-1 alpha-3 country code, such as USA. A code with no published holiday calendar returns 404. |
from | date | Required. Start date, YYYY-MM-DD, from 1900 to 2200. The day itself is not counted, and it does not need to be a business day. |
add | integer | Business days to move from `from`, -1000 to 1000. Negative moves back. 0 returns `from`. Send add or to, not both. |
to | date | End date, YYYY-MM-DD. Counts the business days after from, up to and including to, so counting to the date add returned gives back add. An earlier date gives a negative count. At most 3660 days from `from`. |
Each country's weekend days come from Unicode CLDR weekData (version 48). Public holidays come from our public holidays calendar.
Response
Thursday 26 November 2026 is Thanksgiving, so the three business days after Wednesday 25 November are Friday 27, Monday 30 and Tuesday 1 December.
{
"country": "USA",
"from": "2026-11-25",
"add": 3,
"date": "2026-12-01",
"source": "Narwhal holiday calendar"
}With to the answer counts the business days after from up to and including to.
curl --request GET \
--url "https://api.narwhalapi.com/v1/calendars/business-days/USA?from=2026-11-23&to=2026-12-01" \
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"country": "USA",
"from": "2026-11-23",
"to": "2026-12-01",
"business_days": 5,
"source": "Narwhal holiday calendar"
}Fields
| Field | Type | Meaning |
|---|---|---|
country | string | The code you asked for. |
from | date | The start date you sent. |
add / | integer / date | With add: the number you sent, and the business day reached. Left out with to. |
to / | date / integer | With to: the date you sent, and the count. Left out with add. |
source | string | Where the answer comes from. |
Matching MCP call
Send an authenticated POST / with Accept: application/. The tool is calendars_.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "calendars_get_business_days",
"arguments": {
"country": "USA",
"from": "2026-11-25",
"add": 3
}
}
}Successful results have isError: false, the same response in structuredContent, and serialized JSON in content[0].text. Domain errors have isError: true.
Errors and credits
| Status | Code | When |
|---|---|---|
| 400 | invalid_ | The country is not an ISO alpha-3 code, from is missing or not a date, neither or both of add and to were sent, add is outside -1000 to 1000, or the dates are more than 3660 days apart. |
| 401 | invalid_ | The key is missing or invalid. |
| 402 | insufficient_ | The balance cannot pay for the call. The answer carries top_up_url. |
| 404 | not_found | No holiday calendar is published for the country, or for a year the dates reach. Not charged. |
| 429 | rate_ | The per-minute limit is reached. |
| 503 | database_ | The data store is temporarily unavailable. Retry shortly. |
A successful request costs one call on the Calendars API code, $2 per 1,000 calls. Errors cost nothing. Shared error details
Was this page helpful?