---
title: "Business days API | Narwhal API"
description: "Add business days to a date or count them between two dates for a country, skipping weekends and nationwide public holidays. Parameters, fields and errors."
url: "https://narwhalapi.com/docs/api/calendars/business-days"
---

# 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

| 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.

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

| Field | Type | Meaning |
| --- | --- | --- |
| `country` | string | The code you asked for. |
| `from` | date | The start date you sent. |
| `add / date` | integer / date | With add: the number you sent, and the business day reached. Left out with to. |
| `to / business_days` | 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 /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

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_query` | 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_api_key` | The key is missing or invalid. |
| 402 | `insufficient_credits` | 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_limit_exceeded` | The per-minute limit is reached. |
| 503 | `database_unavailable` | 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](https://narwhalapi.com/docs/errors.md)
[Exchange closures](https://narwhalapi.com/docs/api/calendars/exchange-closures.md) · [Public holidays reference](https://narwhalapi.com/docs/api/calendars.md)

Was this page helpful?
