Name: Business Days API: Holidays and Working Days by Country
Brand: leadharbor
SKU: api-leadharbor-business-days-holidays
Availability: InStock
Author: API Market

Mohammed Samaan

# Business Days and Holidays API

## Overview

The Business Days and Holidays API does business-day arithmetic that knows each country's public holidays and weekend. It has 1 endpoint with four operations selected by the `op` parameter: `is` tells you whether a date is a business day and names the holiday if there is one, `add` adds or subtracts a number of business days and lists every day it skipped, `between` counts the business days between two dates (both dates included), and `holidays` lists a country's public and bank holidays for a year. It covers 207 countries, with optional regions such as US states. Weekends follow the country, for example Friday and Saturday in Saudi Arabia, Bahrain, Egypt and Israel, and you can override them per request with `weekend=friday,saturday`.

It is built for developers working out delivery dates, payment due dates, SLA deadlines and payroll schedules, HR and scheduling tools that need holiday calendars by country, and finance teams counting working days between two dates. Responses are flat JSON with ISO `YYYY-MM-DD` dates, lowercase weekday names, the weekend days used and where they came from (`country_default` or `request`), and a `caveats` list that flags community-maintained data and holidays set by moon sighting. Holiday data comes from the community-maintained date-holidays rule set (CC BY 3.0), credited in every response, not from an official government source, so confirm legal deadlines against the official calendar.

## Features

*   **1 endpoint, 4 operations**: `op=is`, `op=add`, `op=between` and `op=holidays` on `GET /v1/market/business-days`.
*   **Simple inputs**: An ISO 3166-1 alpha-2 `country` code, plus dates as `YYYY-MM-DD`, a whole number of `days`, or a `year`.
*   **207 countries with regions**: Pass `region` for state or regional holidays, for example `CA` for California.
*   **Weekends per country**: Friday and Saturday weekends where the country uses them, and a `weekend` parameter to override the weekend on any call.
*   **Skipped-days list**: `op=add` lists each weekend day and holiday it stepped over, with the holiday name.
*   **Full day counts**: `op=between` returns business days, calendar days, weekend days and holidays that fell on weekdays.
*   **Data source and method**: Holidays are calculated from the date-holidays rule set (CC BY 3.0 data), with `caveats` on every answer.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Delivery and shipping estimates**: Add 5 business days to an order date and skip the destination country's holidays and weekend.
*   **Payment and invoice terms**: Work out "net 10 business days" due dates per country.
*   **SLA and support deadlines**: Count only working days when measuring response or resolution times.
*   **Payroll and HR calendars**: List a year's public and bank holidays for each country you employ people in.
*   **Scheduling**: Check whether a date is a business day before booking a meeting, a bank transfer or a release.
*   **Middle East operations**: Calculate dates with a Friday and Saturday weekend for teams in the UAE, Saudi Arabia and nearby countries.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/leadharbor/business-days-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. Business-day calculations

Runs one of four business-day operations for a country, chosen with `op`. Each operation returns the `country`, the `region` (or `null`), the weekend days used, a `caveats` list and a `meta` object. In `meta`, `user` is `null` and can be ignored, and `attribution` credits the holiday data source.

*   **`op=is`** (default): needs `country` and `date`. Returns the weekday, `is_weekend`, the `holiday` (name and type, or `null`) and `is_business_day`.
*   **`op=add`**: needs `country`, `date` and `days`. Returns `result_date`, `result_weekday`, `start_is_business_day`, `skipped_count` and a `skipped` list with the reason (`holiday` or `weekend`) and holiday name for each day passed over. Use a negative `days` to count backwards.
*   **`op=between`**: needs `country`, `from` and `to`. Returns `business_days`, `calendar_days`, `weekend_days`, `holidays_on_weekdays` and the `holidays` in the range. Both dates are included.
*   **`op=holidays`**: needs `country` and `year`. Returns each holiday with its `date`, `end_date`, `name`, `type` and `weekday`, and the holiday `types_counted`.

**Method:** `GET`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `op` | query | Operation: `is`, `add`, `between` or `holidays`. | string | No | `is` | - |
| `country` | query | ISO 3166-1 alpha-2 country code, for example `US`, `GB` or `AE`. | string | Yes | - | - |
| `region` | query | Region or state code for regional holidays, for example `CA` for California. | string | No | - | - |
| `date` | query | Date as `YYYY-MM-DD`. Used by `op=is` and `op=add`. | string | For `is` and `add` | - | - |
| `days` | query | Whole number of business days to add, negative to subtract. Used by `op=add`. | integer | For `add` | - | 3660 |
| `from` | query | Start date as `YYYY-MM-DD`. Used by `op=between`. | string | For `between` | - | - |
| `to` | query | End date as `YYYY-MM-DD`. Used by `op=between`. | string | For `between` | - | - |
| `year` | query | Year from 1900 to 2100. Used by `op=holidays`. | integer | For `holidays` | - | 2100 |
| `weekend` | query | Comma-separated weekday names that replace the country's weekend, for example `friday,saturday`. | string | No | Country weekend | - |

**Example Request (op=add):**

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

**Example Response (200 OK):**

```json
{
  "op": "add",
  "start_date": "2026-12-23",
  "days": 5,
  "result_date": "2026-12-31",
  "result_weekday": "thursday",
  "start_is_business_day": true,
  "country": "US",
  "region": null,
  "weekend_days": ["saturday", "sunday"],
  "weekend_source": "country_default",
  "skipped_count": 3,
  "skipped": [
    {
      "date": "2026-12-25",
      "reason": "holiday",
      "name": "Christmas Day"
    },
    {
      "date": "2026-12-26",
      "reason": "weekend"
    },
    {
      "date": "2026-12-27",
      "reason": "weekend"
    }
  ],
  "caveats": ["community_maintained_data"],
  "meta": {
    "user": null,
    "attribution": "Holiday data: date-holidays by commenthol, https://github.com/commenthol/date-holidays (ISC code, CC BY 3.0 data)."
  }
}
```

**Example Request (op=add with a custom weekend):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/business-days-holidays/v1/market/business-days?op=add&country=AE&date=2026-12-23&days=5&weekend=friday%2Csaturday" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "op": "add",
  "start_date": "2026-12-23",
  "days": 5,
  "result_date": "2026-12-30",
  "result_weekday": "wednesday",
  "start_is_business_day": true,
  "country": "AE",
  "region": null,
  "weekend_days": ["friday", "saturday"],
  "weekend_source": "request",
  "skipped_count": 2,
  "skipped": [
    {
      "date": "2026-12-25",
      "reason": "weekend"
    },
    {
      "date": "2026-12-26",
      "reason": "weekend"
    }
  ],
  "caveats": ["moon_sighting", "community_maintained_data"],
  "meta": {
    "user": null,
    "attribution": "Holiday data: date-holidays by commenthol, https://github.com/commenthol/date-holidays (ISC code, CC BY 3.0 data)."
  }
}
```

**Example Request (op=between):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/business-days-holidays/v1/market/business-days?op=between&country=US&from=2026-12-21&to=2026-12-31" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "op": "between",
  "from": "2026-12-21",
  "to": "2026-12-31",
  "business_days": 8,
  "calendar_days": 11,
  "weekend_days": 2,
  "holidays_on_weekdays": 1,
  "holidays": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day"
    }
  ],
  "country": "US",
  "region": null,
  "weekend_days_used": ["saturday", "sunday"],
  "weekend_source": "country_default",
  "caveats": ["community_maintained_data"],
  "meta": {
    "user": null,
    "attribution": "Holiday data: date-holidays by commenthol, https://github.com/commenthol/date-holidays (ISC code, CC BY 3.0 data)."
  }
}
```

**Example Request (op=holidays):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/business-days-holidays/v1/market/business-days?op=holidays&country=GB&year=2026" \
  -H "x-api-market-key: YOUR_API_KEY"
```

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

```json
{
  "op": "holidays",
  "country": "GB",
  "region": null,
  "year": 2026,
  "types_counted": ["public", "bank"],
  "holidays": [
    {
      "date": "2026-01-01",
      "end_date": "2026-01-01",
      "name": "New Year's Day",
      "type": "public",
      "weekday": "thursday"
    },
    {
      "date": "2026-12-26",
      "end_date": "2026-12-26",
      "name": "Boxing Day",
      "type": "public",
      "weekday": "saturday"
    },
    {
      "date": "2026-12-28",
      "end_date": "2026-12-28",
      "name": "Boxing Day (substitute day)",
      "type": "public",
      "weekday": "monday"
    }
  ],
  "caveats": ["community_maintained_data"],
  "attribution": "Holiday data: date-holidays by commenthol, https://github.com/commenthol/date-holidays (ISC code, CC BY 3.0 data).",
  "meta": {
    "user": null,
    "attribution": "Holiday data: date-holidays by commenthol, https://github.com/commenthol/date-holidays (ISC code, CC BY 3.0 data)."
  }
}
```

The full 2026 list for `GB` has 8 holidays: New Year's Day, Good Friday, Easter Monday, the Early May and Spring bank holidays, Christmas Day, Boxing Day and the Boxing Day substitute day.

**Example Request (op=is):**

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

**Example Response (200 OK):**

```json
{
  "op": "is",
  "date": "2026-12-25",
  "weekday": "friday",
  "is_weekend": false,
  "holiday": {
    "name": "Christmas Day",
    "type": "public"
  },
  "is_business_day": false,
  "country": "US",
  "region": null,
  "weekend_days": ["saturday", "sunday"],
  "weekend_source": "country_default",
  "caveats": ["community_maintained_data"],
  "meta": {
    "user": null,
    "attribution": "Holiday data: date-holidays by commenthol, https://github.com/commenthol/date-holidays (ISC code, CC BY 3.0 data)."
  }
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The calculation succeeded. Check `caveats` for dates that depend on moon sighting. |
| 400 | Bad Request | A field is missing or invalid, and the message names the field, for example a bad date format or `days` above 3660. Also returned for a country with no holiday data, such as Oman, Qatar or Kuwait. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The request path does not exist. Check that it is `/v1/market/business-days`. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

The Free trial, Starter and PAYG plans each allow 10 requests per second. The Free trial is a 7-day trial with 500 calls, Starter includes 10,000 calls with extra calls billed at $0.001 each, and PAYG charges $0.001 per call with no subscription. Every call counts as one call, whichever operation you use. Requests above the per-second limit, or after the Free trial calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which says how many seconds to wait. In our tests every operation answered in about 0.5 to 0.6 seconds.

## FAQ

**Does `op=between` include the start and end dates?**

Yes. Both dates are counted. From `2026-12-21` to `2026-12-31` in the US is 11 calendar days, of which 2 are weekend days and 1 is Christmas Day, leaving 8 business days.

**Does `op=add` count the start date?**

No. Adding 5 business days to Wednesday `2026-12-23` in the US gives Thursday `2026-12-31`: the 24th, 28th, 29th, 30th and 31st are counted, and Christmas Day and the weekend are listed in `skipped`. `start_is_business_day` tells you separately whether the start date itself was a business day.

**How do I use a different weekend?**

Pass `weekend` with comma-separated day names, for example `weekend=friday,saturday`. The response then shows `weekend_source: "request"` instead of `country_default`. Countries that already use a Friday and Saturday weekend, such as Saudi Arabia, Bahrain, Egypt and Israel, get it without the parameter.

**Which countries are covered?**

207 countries, by ISO 3166-1 alpha-2 code, with optional regions such as US states. Some countries, for example Oman, Qatar and Kuwait, have no holiday data and return a `400`.

**Can I rely on these dates for legal or contractual deadlines?**

Use them as a strong default and confirm legal deadlines with the official calendar. The data comes from the community-maintained date-holidays rule set, not a government source, and every answer carries a `caveats` list. Holidays set by moon sighting can move by a day, and those answers include the `moon_sighting` caveat.

**What do the `meta` fields mean?**

`meta.user` is always `null` for API.market calls and you can ignore it. `meta.attribution` credits the holiday data source, which is published under CC BY 3.0.

**How far can I add or subtract days?**

Up to 3,660 business days in either direction with `days`, and `op=holidays` accepts years from 1900 to 2100.

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


Business days API that adds or counts working days, checks a date and lists public holidays for 207 countries, with regional holidays and custom weekends.

Business Days API: Holidays and Working Days by Country

PAYG