Name: Public Holidays and Business Days API: 207 Countries
Brand: rasareka
SKU: api-rasareka-public-holidays
Availability: InStock
Author: API Market

Khairul Fauzy Khairudin

# Public Holidays API

## Overview

The Public Holidays API returns public holidays for 207 countries and their states or provinces, plus business day calculations. List every holiday in a year with local and English names, holiday type and substitute days, check whether a date is a holiday or a business day, list the next holidays, count business days between two dates, or add a number of business days to a date. Weekends can be customised for countries that do not rest on Saturday and Sunday.

It is built for developers of delivery date estimates, SLA and due date calculators, payroll and HR leave tools, booking calendars and invoicing software. In our tests California 2026 returned 13 public holidays, 2026-12-28 in the UK came back as the Boxing Day substitute holiday, December 2026 in the US had 22 business days, and adding 3 business days to 2026-12-23 returned 2026-12-29, skipping Christmas and the weekend.

## Features

*   **7 endpoints**: holidays, is-holiday, next holidays, business day count, add business days, countries and states.
*   **207 countries**: with states and provinces where holidays differ.
*   **Holiday types**: public, bank, school, optional and observance.
*   **Substitute days**: observed days when a holiday falls on a weekend.
*   **Custom weekends**: for example `fri,sat` for the Middle East.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Delivery estimates**: skip holidays when promising a delivery date.
*   **SLA tracking**: count business days to a deadline.
*   **Payroll and HR**: plan pay dates and leave around holidays.
*   **Booking calendars**: block out public holidays.
*   **Invoicing**: set due dates in business days.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/rasareka/public-holidays
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Holidays in a year

Lists every holiday for a country and year, optionally for a state.

**Method:** `GET`

**Endpoint:** `/holidays/v1/holidays`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | Two-letter country code, for example `US` | string | Yes | - | - |
| `year` | query | Year, for example `2026` | integer | No | current year | - |
| `state` | query | State or province code, see `/holidays/v1/countries/{code}/states` | string | No | - | - |
| `types` | query | `public`, `bank`, `school`, `optional`, `observance` or `all` | string | No | `public` | - |
| `lang` | query | Language for local names | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/holidays?country=US&year=2026&state=CA' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "US",
  "country_name": "United States of America",
  "state": "CA",
  "region": null,
  "year": 2026,
  "count": 13,
  "holidays": [
    {
      "date": "2026-01-01",
      "day": "thu",
      "name": "New Year's Day",
      "name_en": "New Year's Day",
      "type": "public",
      "substitute": false,
      "start": "2026-01-01T08:00:00.000Z",
      "end": "2026-01-02T08:00:00.000Z",
      "note": null
    },
    {
      "date": "2026-01-19",
      "day": "mon",
      "name": "Martin Luther King Jr. Day",
      "name_en": "Martin Luther King Jr. Day",
      "type": "public",
      "substitute": false,
      "start": "2026-01-19T08:00:00.000Z",
      "end": "2026-01-20T08:00:00.000Z",
      "note": null
    }
  ],
  "attribution": "Holiday data from the date-holidays project (CC-BY-3.0), https://github.com/commenthol/date-holidays"
}
```

The `holidays` list above is shortened to two of 13 entries.

#### 2. Is a date a holiday?

Tells you whether a date is a holiday, a weekend day or a business day.

**Method:** `GET`

**Endpoint:** `/holidays/v1/is-holiday`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | Two-letter country code, for example `US` | string | Yes | - | - |
| `date` | query | Date as `YYYY-MM-DD` | string | No | today | - |
| `state` | query | State or province code, see `/holidays/v1/countries/{code}/states` | string | No | - | - |
| `weekend` | query | Weekend days, for example `fri,sat` | string | No | `sat,sun` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/is-holiday?country=GB&date=2026-12-28' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "GB",
  "country_name": "United Kingdom",
  "state": null,
  "region": null,
  "date": "2026-12-28",
  "day": "mon",
  "is_holiday": true,
  "is_weekend": false,
  "is_business_day": false,
  "holidays": [
    {
      "date": "2026-12-28",
      "day": "mon",
      "name": "Boxing Day (substitute day)",
      "name_en": "Boxing Day (substitute day)",
      "type": "public",
      "substitute": true,
      "start": "2026-12-28T00:00:00.000Z",
      "end": "2026-12-29T00:00:00.000Z",
      "note": null
    }
  ]
}
```

#### 3. Next holidays

Lists the upcoming holidays with the number of days until each.

**Method:** `GET`

**Endpoint:** `/holidays/v1/next`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | Two-letter country code, for example `US` | string | Yes | - | - |
| `count` | query | Number of holidays to return | integer | No | - | - |
| `from` | query | Start date as `YYYY-MM-DD` | string | No | today | - |
| `state` | query | State or province code, see `/holidays/v1/countries/{code}/states` | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/next?country=DE&count=3&from=2026-11-12' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "DE",
  "country_name": "Germany",
  "state": null,
  "region": null,
  "from": "2026-11-12",
  "count": 3,
  "holidays": [
    {
      "date": "2026-12-25",
      "day": "fri",
      "name": "Christmas Day",
      "name_en": "Christmas Day",
      "type": "public",
      "substitute": false,
      "start": "2026-12-24T23:00:00.000Z",
      "end": "2026-12-25T23:00:00.000Z",
      "note": null,
      "days_away": 43
    },
    {
      "date": "2026-12-26",
      "day": "sat",
      "name": "Boxing Day",
      "name_en": "Boxing Day",
      "type": "public",
      "substitute": false,
      "start": "2026-12-25T23:00:00.000Z",
      "end": "2026-12-26T23:00:00.000Z",
      "note": null,
      "days_away": 44
    }
  ]
}
```

The `holidays` list above is shortened to two of three entries.

#### 4. Count business days

Counts business days between two dates, both included, and lists the holidays that fell on weekdays.

**Method:** `GET`

**Endpoint:** `/holidays/v1/business-days`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | Two-letter country code, for example `US` | string | Yes | - | - |
| `start` | query | Start date as `YYYY-MM-DD` | string | Yes | - | - |
| `end` | query | End date as `YYYY-MM-DD` | string | Yes | - | - |
| `state` | query | State or province code, see `/holidays/v1/countries/{code}/states` | string | No | - | - |
| `weekend` | query | Weekend days, for example `fri,sat` | string | No | `sat,sun` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/business-days?country=US&start=2026-12-01&end=2026-12-31' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "US",
  "country_name": "United States of America",
  "state": null,
  "region": null,
  "start": "2026-12-01",
  "end": "2026-12-31",
  "total_days": 31,
  "business_days": 22,
  "weekend_days": 8,
  "holiday_days": 1,
  "holidays_on_weekdays": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day"
    }
  ]
}
```

#### 5. Add business days

Adds or subtracts business days from a date, skipping weekends and holidays.

**Method:** `GET`

**Endpoint:** `/holidays/v1/add-business-days`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `country` | query | Two-letter country code, for example `US` | string | Yes | - | - |
| `date` | query | Start date as `YYYY-MM-DD` | string | Yes | - | - |
| `days` | query | Business days to add, negative to subtract | integer | Yes | - | - |
| `state` | query | State or province code, see `/holidays/v1/countries/{code}/states` | string | No | - | - |
| `weekend` | query | Weekend days, for example `fri,sat` | string | No | `sat,sun` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/add-business-days?country=US&date=2026-12-23&days=3' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "US",
  "country_name": "United States of America",
  "state": null,
  "region": null,
  "start_date": "2026-12-23",
  "business_days_added": 3,
  "result_date": "2026-12-29",
  "result_day": "tue",
  "holidays_skipped": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day"
    }
  ]
}
```

#### 6. Supported countries

Lists the supported countries and whether each has states.

**Method:** `GET`

**Endpoint:** `/holidays/v1/countries`

**Parameters:**

None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/countries' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "count": 207,
  "countries": [
    {
      "code": "AX",
      "name": "Åland Islands",
      "has_states": false
    },
    {
      "code": "AL",
      "name": "Albania",
      "has_states": true
    },
    {
      "code": "DZ",
      "name": "Algeria",
      "has_states": false
    }
  ],
  "attribution": "Holiday data from the date-holidays project (CC-BY-3.0), https://github.com/commenthol/date-holidays"
}
```

The `countries` list above is shortened to three of 207 entries.

#### 7. States of a country

Lists the states or provinces of a country with their codes.

**Method:** `GET`

**Endpoint:** `/holidays/v1/countries/{code}/states`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `code` | path | Two-letter country code, for example `US` | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/rasareka/public-holidays/holidays/v1/countries/US/states' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "US",
  "name": "United States of America",
  "states": [
    {
      "code": "AL",
      "name": "Alabama"
    },
    {
      "code": "AK",
      "name": "Alaska"
    },
    {
      "code": "AZ",
      "name": "Arizona"
    }
  ]
}
```

The `states` list above is shortened to three entries.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 400 | Bad Request | A parameter is missing or invalid, for example `Unsupported country 'XX'. See /v1/countries`. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API. Check the Base URL and path. |
| 429 | Too Many Requests | You went over 10 requests per second or used up the quota of your plan. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second, and each subscription plan has its own monthly quota. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Where does the holiday data come from?**
    From the open date-holidays project (CC BY 3.0).

*   **Are lunar and Islamic holidays exact?**
    They are calculated, so in some countries they can differ by a day from the official announcement.

*   **Are both dates included in the business day count?**
    Yes, `start` and `end` are both counted.

*   **How do I handle a Friday and Saturday weekend?**
    Pass `weekend=fri,sat`.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Public holidays for 207 countries and their states, plus business day maths: is-holiday checks, upcoming holidays, count and add working days.

Public Holidays and Business Days API: 207 Countries