Name: Public Holidays API: 250 Countries and Business Days
Brand: compasslab-1
SKU: api-compasslab-1-public-holidays
Availability: InStock
Author: API Market

WPTOOLS

# Public Holidays and Business Days API

## Overview

The Public Holidays and Business Days API gives you official public holidays for 250 countries and territories, including their states and regions, for every year from 1990 to 2050. Each holiday comes with its English and local name, its type, and whether it is observed nationwide or only in some subdivisions. On top of the calendar data, three business-day endpoints do the date math most products need: check whether a date is a working day, add or subtract business days, and count business days between two dates.

It is built for developers of payroll, HR, scheduling, logistics, invoicing and booking software who need correct working-day calculations across many countries. Weekends follow each country's own working week (including Friday-Saturday weekends), you can override the weekend, and you can add your company's own closing days with `extra_holidays`. All responses are compact JSON.

## Features

*   **5 endpoints**: One holiday calendar endpoint, one country lookup and three business-day calculators.
*   **250 countries and territories**: With their states, regions and provinces, from 1990 to 2050.
*   **Regional accuracy**: Filter by `subdivision` to get exactly the holidays one state or region observes.
*   **Local names and types**: Each holiday includes its English name, local-language name and type (for example public or bank).
*   **Business-day math**: Is-business-day checks with a reason, add or subtract business days, and count business days between dates.
*   **Custom weekends and closing days**: Override the weekend with `weekend` and add company closing days with `extra_holidays`.
*   **Substitute holidays**: Holidays moved off a weekend are included where the country observes them.
*   **Fast JSON responses**: Lightweight responses that are easy to cache.

## Use Cases

*   **Payroll and HR platforms**: Calculate pay dates, leave balances and working days per employee country.
*   **Logistics and e-commerce**: Estimate delivery dates that skip weekends and public holidays.
*   **Invoicing and fintech**: Compute payment due dates and settlement days for net-30 style terms.
*   **Scheduling and booking apps**: Block holidays in calendars and suggest the next available working day.
*   **Customer support SLAs**: Measure response deadlines in business days per region.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

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

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

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

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Public Holidays for a Year

Returns every holiday of one year for a country, with the date, English and local name, holiday type, and whether it is nationwide or only observed in some subdivisions. Pass `subdivision` to get exactly what one state or region observes.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 code | string | Yes | - | 2 chars |
| year | query | Year | integer | Yes | - | 2050 |
| subdivision | query | State, region or province code (or name), e.g. BY for Bavaria | string | No | - | - |
| language | query | Language of `name`, e.g. en, de, fr. Default English where available | string | No | - | - |
| types | query | Comma-separated holiday categories, e.g. public,bank (see the country's types) | string | No | `public` | 100 chars |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/public-holidays/v1/holidays?country=DE&year=2026&subdivision=BY" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "country_code": "DE",
  "country_name": "Germany",
  "subdivision": "BY",
  "year": 2026,
  "language": "en_US",
  "types": [
    "public"
  ],
  "count": 12,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "local_name": "Neujahr",
      "type": "public",
      "nationwide": true,
      "subdivisions": []
    },
    {
      "date": "2026-01-06",
      "name": "Epiphany",
      "local_name": "Heilige Drei Könige",
      "type": "public",
      "nationwide": false,
      "subdivisions": [
        "Augsburg",
        "BW"
      ]
    }
  ]
}
```

#### 2. List Supported Countries

Returns all 250 supported countries and territories with their subdivisions, languages, holiday types and weekend days. Use it to look up valid `country` and `subdivision` codes.

**Method:** `GET`

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

**Parameters:**

None.

**Example Request:**

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

**Example Response (200 OK, abridged):**

```json
{
  "count": 250,
  "countries": [
    {
      "code": "AD",
      "name": "Andorra",
      "subdivisions": [
        {
          "code": "02",
          "name": "Canillo"
        },
        {
          "code": "03",
          "name": "Encamp"
        }
      ],
      "languages": [
        "ca",
        "en_US"
      ],
      "default_language": "ca",
      "types": [
        "government",
        "public"
      ],
      "weekend": [
        "sat",
        "sun"
      ]
    },
    {
      "code": "AE",
      "name": "United Arab Emirates",
      "subdivisions": [],
      "languages": [
        "ar",
        "en_US"
      ],
      "default_language": "ar",
      "types": [
        "government",
        "optional"
      ],
      "weekend": [
        "sat",
        "sun"
      ]
    }
  ]
}
```

#### 3. Check a Business Day

Tells you whether a date is a business day in a country and, if not, why: weekend, public holiday, or one of your own closing days.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 code | string | Yes | - | 2 chars |
| date | query | ISO date | string | Yes | - | - |
| subdivision | query | State, region or province code (or name), e.g. BY for Bavaria | string | No | - | - |
| weekend | query | Override the country's weekend, e.g. fri,sat | string | No | - | - |
| extra_holidays | query | Your own closing days, comma-separated ISO dates (up to 100) | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/public-holidays/v1/business-days/is?country=US&date=2026-12-25" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "country_code": "US",
  "subdivision": null,
  "date": "2026-12-25",
  "is_business_day": false,
  "reason": "holiday",
  "holiday_name": "Christmas Day",
  "weekend": [
    "sat",
    "sun"
  ]
}
```

#### 4. Add Business Days

Adds (or, with a negative number, subtracts) business days to a date, skipping weekends and holidays. Use it for due dates, delivery estimates and payment terms.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 code | string | Yes | - | 2 chars |
| date | query | Start date (ISO) | string | Yes | - | - |
| days | query | Business days to add; negative goes back | integer | Yes | - | 1000 |
| subdivision | query | State, region or province code (or name), e.g. BY for Bavaria | string | No | - | - |
| weekend | query | Override the country's weekend, e.g. fri,sat | string | No | - | - |
| extra_holidays | query | Your own closing days, comma-separated ISO dates (up to 100) | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/public-holidays/v1/business-days/add?country=GB&date=2026-12-22&days=5" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "country_code": "GB",
  "subdivision": null,
  "start": "2026-12-22",
  "days": 5,
  "result": "2026-12-31",
  "weekend": [
    "sat",
    "sun"
  ]
}
```

#### 5. Count Business Days Between Dates

Counts the calendar days and business days between two dates and lists the holidays that fall in the range.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 code | string | Yes | - | 2 chars |
| start | query | First day (ISO, included) | string | Yes | - | - |
| end | query | Last day (ISO, included) | string | Yes | - | - |
| subdivision | query | State, region or province code (or name), e.g. BY for Bavaria | string | No | - | - |
| weekend | query | Override the country's weekend, e.g. fri,sat | string | No | - | - |
| extra_holidays | query | Your own closing days, comma-separated ISO dates (up to 100) | string | No | - | - |

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "country_code": "DE",
  "subdivision": null,
  "start": "2026-12-01",
  "end": "2026-12-31",
  "calendar_days": 31,
  "business_days": 22,
  "weekend_days": 7,
  "holiday_days": 2,
  "holidays_in_range": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "on_weekend": false
    },
    {
      "date": "2026-12-26",
      "name": "Second Day of Christmas",
      "on_weekend": true
    }
  ],
  "weekend": [
    "sat",
    "sun"
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response contains the requested data. |
| 400 | Bad Request | A parameter is malformed, for example a date that is not in YYYY-MM-DD format. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is invalid. |
| 403 | Forbidden | Your API.market subscription does not include this endpoint. |
| 404 | Not Found | The country or subdivision code is not supported, for example `Unknown subdivision`. Use `/v1/holidays/countries` to find valid codes. |
| 422 | Unprocessable Entity | A required parameter such as `country` or `date` is missing. |
| 429 | Too Many Requests | You exceeded your plan's requests per second or your monthly quota. |
| 500 | Internal Server Error | An unexpected error occurred on the server. Retry after a short wait. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry with backoff. |

## Rate Limits

Each successful request uses 1 API unit. The Free plan includes 1,000 units as a 7-day trial at 1 request per second. Pro ($4.99/month) includes 20,000 units at 5 requests per second, Ultra ($14.99/month) 100,000 units at 10 requests per second, and Mega ($39/month) 500,000 units at 20 requests per second. Paid plans continue past the quota at $0.0002 per extra unit.

If you exceed the per-second limit you receive a `429 Too Many Requests` response. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **Which country and subdivision codes should I use?**

    Use ISO 3166-1 alpha-2 country codes such as `US`, `DE` or `GB`, and the subdivision codes listed by `/v1/holidays/countries` (for example `BY` for Bavaria).

*   **Which years are covered?**

    Every year from 1990 to 2050.

*   **Can I add my company's own closing days?**

    Yes. Pass them as `extra_holidays` (comma-separated YYYY-MM-DD dates) on the business-day endpoints.

*   **Can I change the weekend?**

    Yes. The `weekend` parameter overrides the country's default weekend days.

*   **Does `/v1/business-days/add` accept negative numbers?**

    Yes. A negative `days` value subtracts business days from the date.

*   **Where does the holiday data come from?**

    From the open-source `holidays` library, which is maintained by a large community and updated as governments announce changes.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Get public holidays for 250 countries and regions from 1990 to 2050, and calculate business days, due dates and working days with one JSON API.

Public Holidays API: 250 Countries and Business Days

Free