Browse all documentation

Business days API reference

Add business days to a date or count them between two dates, using our public holidays.

Request

GET /v1/calendars/business-days/{country} 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.

Three business days after 25 November 2026 in the United States
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

NameTypeRule
countrystringRequired path value. ISO 3166-1 alpha-3 country code, such as USA. A code with no published holiday calendar returns 404.
fromdateRequired. 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.
addintegerBusiness days to move from `from`, -1000 to 1000. Negative moves back. 0 returns `from`. Send add or to, not both.
todateEnd 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.

200 OK
{
  "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.

Count between two dates
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"
200 OK
{
  "country": "USA",
  "from": "2026-11-23",
  "to": "2026-12-01",
  "business_days": 5,
  "source": "Narwhal holiday calendar"
}

Fields

FieldTypeMeaning
countrystringThe code you asked for.
fromdateThe start date you sent.
add / dateinteger / dateWith add: the number you sent, and the business day reached. Left out with to.
to / business_daysdate / integerWith to: the date you sent, and the count. Left out with add.
sourcestringWhere the answer comes from.

Matching MCP call

Send an authenticated POST /mcp with Accept: application/json, text/event-stream. The tool is calendars_get_business_days.

{
  "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

StatusCodeWhen
400invalid_queryThe 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.
401invalid_api_keyThe key is missing or invalid.
402insufficient_creditsThe balance cannot pay for the call. The answer carries top_up_url.
404not_foundNo holiday calendar is published for the country, or for a year the dates reach. Not charged.
429rate_limit_exceededThe per-minute limit is reached.
503database_unavailableThe 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

Exchange closures · Public holidays reference

Was this page helpful?