# Public Holidays & Business Days API — public holidays by country and year, working-day checks, business-day counts, upcoming holidays and a long-weekend finder

> public holidays for a country + year (full Nager fields + derived year/weekday/nationwide)
> ReefAPI engine `holidays` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/holidays/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /holidays/v1/holidays — 1 credit
public holidays for a country + year (full Nager fields + derived year/weekday/nationwide)

**Parameters:**
- `country` (string, required) — 2-letter ISO-3166 country code (e.g. US, GB, DE, TR, JP). 123 countries supported — call action='countries' for the full set. Case-insensitive.
- `year` (integer, required) — 4-digit year (supported range 1900-2200).

**Returns:** country, year, count, holidays[] (date, name, localName, types[], global, counties[], weekday, nationwide)

**Example request body:**
```json
{
  "country": "US",
  "year": 2026
}
```

### POST /holidays/v1/is_workday — 1 credit
is a given date a working day for a country? (weekend + public-holiday aware; reasons[] explain)

**Parameters:**
- `country` (string, required) — 2-letter ISO-3166 country code (e.g. US, GB, DE, TR, JP). 123 countries supported — call action='countries' for the full set. Case-insensitive.
- `date` (string, required) — The date to test, in ISO format YYYY-MM-DD.
- `weekend` (string, optional) — Override the weekend definition with day names (e.g. 'Sat,Sun' or 'Fri,Sat'). Defaults to Sat+Sun (Fri+Sat for EG/BD).
- `types` (string, optional) — Which holiday types count as a day off (comma-separated, case-insensitive). Defaults to Public only. [one of: Public, Bank, School, Authorities, Optional, Observance]
- `subdivision` (string, optional) — Optional ISO-3166-2 subdivision code (e.g. US-CA, GB-SCT) for region-precise business days. Omit for nationwide. Case-insensitive.

**Returns:** date, country, weekday, is_workday, is_weekend, is_public_holiday, reasons[], holidays[], weekend_definition[]

**Example request body:**
```json
{
  "country": "US",
  "date": "2026-01-01"
}
```

### POST /holidays/v1/workday_count — 1 credit
business-day count over a date range: workdays/weekend_days/holiday_days + the holidays in range

**Parameters:**
- `country` (string, required) — 2-letter ISO-3166 country code (e.g. US, GB, DE, TR, JP). 123 countries supported — call action='countries' for the full set. Case-insensitive.
- `start` (string, required) — Range start date (inclusive), ISO YYYY-MM-DD.
- `end` (string, required) — Range end date (inclusive), ISO YYYY-MM-DD. Max range ~10 years.
- `weekend` (string, optional) — Override the weekend definition with day names (e.g. 'Sat,Sun' or 'Fri,Sat'). Defaults to Sat+Sun (Fri+Sat for EG/BD).
- `types` (string, optional) — Which holiday types count as a day off (comma-separated, case-insensitive). Defaults to Public only. [one of: Public, Bank, School, Authorities, Optional, Observance]
- `subdivision` (string, optional) — Optional ISO-3166-2 subdivision code (e.g. US-CA, GB-SCT) for region-precise business days. Omit for nationwide. Case-insensitive.

**Returns:** country, start, end, total_days, workdays, weekend_days, holiday_days, holidays[] (in range), weekend_definition[]

**Example request body:**
```json
{
  "country": "US",
  "start": "2026-01-01",
  "end": "2026-01-31"
}
```

### POST /holidays/v1/next_holidays — 1 credit
upcoming public holidays (next ~365 days) with daysUntil

**Parameters:**
- `country` (string, required) — 2-letter ISO-3166 country code (e.g. US, GB, DE, TR, JP). 123 countries supported — call action='countries' for the full set. Case-insensitive.
- `today` (string, optional) — Optional 'as of' date (ISO YYYY-MM-DD) to compute daysUntil from; defaults to the current UTC date.

**Returns:** country, asOf, count, holidays[] (full fields + daysUntil)

**Example request body:**
```json
{
  "country": "US"
}
```

### POST /holidays/v1/long_weekends — 1 credit
long-weekend windows for a country + year (+ bridge-day suggestions)

**Parameters:**
- `country` (string, required) — 2-letter ISO-3166 country code (e.g. US, GB, DE, TR, JP). 123 countries supported — call action='countries' for the full set. Case-insensitive.
- `year` (integer, required) — 4-digit year (supported range 1900-2200).

**Returns:** country, year, count, longWeekends[] (startDate, endDate, dayCount, needBridgeDay, startWeekday)

**Example request body:**
```json
{
  "country": "US",
  "year": 2026
}
```

### POST /holidays/v1/countries — 0 credits
the supported country set (code → name)

**Parameters:** none

**Returns:** count, countries[] (countryCode, name)

## More
- Try it live, no code: https://reefapi.com/playground?engine=holidays
- Human docs page: https://reefapi.com/docs/holidays
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt