Name: Public Holidays API: Workday Checks for 248 Countries
Brand: visionwell
SKU: api-visionwell-holidaycal
Availability: InStock
Author: API Market

binbin7418-dotcom

# HolidayCal Public Holidays and Workday API

## Overview

HolidayCal gives your application the real calendar for 248 countries and territories. Four endpoints work together: one lists the public holidays for a country and year, one answers whether a given date is a working day, one adds or subtracts working days from a date, and one lists every supported country. The holiday data comes from the open-source python-holidays dataset (MIT License), bundled into the service, and covers the years 2019 to 2032.

It is built for developers of scheduling, logistics, HR and payroll software who need delivery promises, SLA timers and project dates that respect local calendars. Responses are finished answers in JSON: the holiday names in English and the local language, a yes or no workday verdict with the reason, and a list of every day that was skipped in a workday calculation.

## Features

*   **4 endpoints**: holiday lists, workday checks, workday arithmetic and the country list.
*   **Coverage**: 248 countries and territories, years 2019 to 2032.
*   **Local names**: every holiday carries its English name and its local name.
*   **Workday verdicts**: weekends and public holidays are combined into one answer, with the reason returned.
*   **Make-up workdays**: official adjusted working days are honoured where the dataset defines them, such as in China.
*   **Auditable arithmetic**: the add-workdays response lists every skipped date and why it was skipped.
*   **Data source**: the python-holidays open-source dataset (MIT License), bundled into the service.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **Delivery estimates**: add working days to an order date so promised dates already account for local holidays.
*   **SLA timers**: count only working days for support and contract deadlines.
*   **Payroll teams**: check whether a cut-off date is a working day before scheduling a run.
*   **Project planners**: shift task dates across public holidays in each country.
*   **Booking products**: block out public holidays in calendars and booking flows.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/visionwell/holidaycal
```

### Authentication

Every request must include 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

Returns the public holidays for a country and year, with English and local names.

**Method:** `GET`

**Endpoint:** `/holidays`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 country code, e.g. US or CN. | string | Yes | - | - |
| year | query | Four-digit year, e.g. 2026. | integer | Yes | - | - |

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "country": "US",
  "year": 2026,
  "count": 12,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "localName": "New Year's Day",
      "fixed": true,
      "global": true,
      "types": [
        "Public"
      ]
    },
    {
      "date": "2026-01-19",
      "name": "Martin Luther King Jr. Day",
      "localName": "Martin Luther King Jr. Day",
      "fixed": false,
      "global": true,
      "types": [
        "Public"
      ]
    },
    {
      "date": "2026-02-16",
      "name": "Washington's Birthday",
      "localName": "Washington's Birthday",
      "fixed": false,
      "global": true,
      "types": [
        "Public"
      ]
    }
  ],
  "workedWeekendDays": [],
  "source": "holidays open-source dataset (MIT License), bundled"
}
```

#### 2. Is workday

Answers whether a date is a working day in a country and says whether it is a weekend or a holiday.

**Method:** `GET`

**Endpoint:** `/is-workday`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 country code, e.g. CN or US. | string | Yes | - | - |
| date | query | Date to check, in YYYY-MM-DD format. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/visionwell/holidaycal/is-workday?country=CN&date=2026-10-01' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "CN",
  "date": "2026-10-01",
  "dayOfWeek": "Thu",
  "isWeekend": false,
  "isHoliday": true,
  "holiday": {
    "name": "National Day",
    "localName": "国庆节"
  },
  "isWorkday": false,
  "note": "Weekend = Saturday/Sunday, except official make-up working days the dataset defines for some countries (e.g. China's adjusted workdays). Holiday data per the bundled dataset.",
  "source": "holidays open-source dataset (MIT License), bundled"
}
```

#### 3. Add workdays

Adds working days to a date, or subtracts them with a negative number, and lists every date it skipped.

**Method:** `GET`

**Endpoint:** `/add-workdays`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| country | query | ISO 3166-1 alpha-2 country code, e.g. US or CN. | string | Yes | - | - |
| date | query | Start date, in YYYY-MM-DD format. | string | Yes | - | - |
| days | query | Number of working days to add (use a negative value to subtract). | integer | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/visionwell/holidaycal/add-workdays?country=US&date=2026-11-06&days=5' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "country": "US",
  "startDate": "2026-11-06",
  "days": 5,
  "resultDate": "2026-11-16",
  "skippedCount": 5,
  "skipped": [
    {
      "date": "2026-11-07",
      "reason": "weekend"
    },
    {
      "date": "2026-11-08",
      "reason": "weekend"
    },
    {
      "date": "2026-11-11",
      "reason": "holiday: Veterans Day"
    },
    {
      "date": "2026-11-14",
      "reason": "weekend"
    },
    {
      "date": "2026-11-15",
      "reason": "weekend"
    }
  ],
  "note": "Counts business days strictly after (or before, for negative days) the start date, skipping Sat/Sun (except dataset-defined make-up working days) and public holidays.",
  "source": "holidays open-source dataset (MIT License), bundled"
}
```

#### 4. Countries

Lists every supported country and territory with its ISO code and English name.

**Method:** `GET`

**Endpoint:** `/countries`

**Parameters:** None.

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "count": 248,
  "countries": [
    {
      "countryCode": "AD",
      "name": "Andorra"
    },
    {
      "countryCode": "AE",
      "name": "United Arab Emirates"
    },
    {
      "countryCode": "AF",
      "name": "Afghanistan"
    }
  ],
  "source": "holidays open-source dataset (MIT License), bundled"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | There is no data for that country or year. Coverage is the country list from `/countries` and the years 2019 to 2032. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **Which years are covered?**

    The years 2019 to 2032. A request outside that range returns a 404 that names the covered years.

*   **How do I know if a country is supported?**

    Call `/countries`. A code that is not in the list, such as `BV` for Bouvet Island, returns a 404.

*   **Does a holiday always mean a day off?**

    A workday verdict follows the bundled dataset, so check the official source when a date has legal or payroll consequences.

*   **How does the API count workdays?**

    `/add-workdays` counts working days strictly after the start date, or before it for negative values, skipping weekends and public holidays.

*   **Why do some holidays say estimated?**

    Dates set by a lunar calendar can be marked as estimated in the dataset, for example Eid al-Fitr in some countries.

## 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, is-workday answers and add-workdays math for 248 countries and territories as JSON. Holiday data covers 2019 to 2032.

Public Holidays API: Workday Checks for 248 Countries