# Business Days & Holidays API - 200 Countries, Time Zones (`that_red_bird/business-calendar-api`) Actor

Public holidays for about 200 countries, add-N-working-days maths that skips weekends and local holidays, business-day checks and time zone lookup in one call. Nager.Date plus offline data. Batch thousands of queries for SLA, HR and delivery tools.

- **URL**: https://apify.com/that_red_bird/business-calendar-api.md
- **Developed by:** [mohamed alaya](https://apify.com/that_red_bird) (community)
- **Categories:** Developer tools, Automation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 query answereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Business Days & Holidays API - 200 Countries, Time Zones

Public holidays, "add N working days" maths, working days between two dates, business-day checks and time zone lookup in one Actor call.
For people building schedulers, SLA and deadline calculators, HR and payroll tools, logistics ETAs and AI agents who need to know "when is 5 working days from today in Germany?" without paying per call for a holiday API.

### Quick start

Run with empty input: you get the current year's public holidays of the US. Change **What to calculate** and the fields, or send a list of queries in **Batch queries** to answer thousands in one run.

### Input examples

**1. Holidays of several countries**

```json
{ "operation": "holidays", "country": "US,GB,FR,TN", "year": 2027 }
```

**2. Deadline: 10 working days from a date, Bavaria**

```json
{ "operation": "addWorkingDays", "country": "DE", "region": "BY", "date": "2026-12-18", "days": 10 }
```

**3. A batch of mixed queries**

```json
{
  "queries": [
    { "op": "isBusinessDay", "country": "SA", "date": "2026-10-09" },
    { "op": "workingDaysBetween", "country": "FR", "start": "2026-05-01", "end": "2026-05-31" },
    { "op": "timezone", "city": "Tunis" },
    { "op": "timezone", "latitude": "40.7", "longitude": "-74.0", "at": "2026-07-01T12:00:00Z" }
  ]
}
```

### Operations

| `op` | Needs | Returns |
|---|---|---|
| `holidays` | `country`, optional `region`, `year` | One row per holiday: `date`, `weekday`, `name`, `localName`, `types`, `global`, `regions`, `source`. |
| `addWorkingDays` | `country`, `start` (or `date`), `days` (negative = backwards) | `resultDate`, `resultWeekday`, `calendarDays`, skipped weekend days and holidays. |
| `workingDaysBetween` | `country`, `start`, `end`, `inclusive` (default true: both ends counted) | `workingDays`, `weekendDays`, `holidaysInRange`. |
| `isBusinessDay` | `country`, `date` | `isBusinessDay`, `isWeekend`, `isHoliday`, `holidayName`. |
| `timezone` | `latitude` + `longitude` or `city`, optional `at` | `timezone`, `utcOffset`, `observesDst`, `isDstNow`, `localTime`. |

### Input guide

| Field | What it does |
|---|---|
| `operation`, `country`, `region`, `year`, `date`, `endDate`, `days`, `latitude`, `longitude`, `city` | One simple query (several countries allowed for holidays). |
| `queries` | A batch; replaces the simple fields. Each item uses the keys above (`op`, `country`, `start`, ...). |
| `holidaySource` | `auto` (Nager.Date, then offline), `nager`, or `offline` (never calls the web). |
| `includeObservances` | Also count observances and optional days (off by default). |
| `weekend` | Override, e.g. `fri,sat`. Default is by country. |
| `maxQueries` | Safety limit. |

### Sample rows

```json
{ "type": "holiday", "country": "TN", "year": 2026, "date": "2026-01-01", "weekday": "Thursday", "name": "New Year's Day", "localName": "عيد رأس السنة", "types": ["Public"], "global": true, "source": "date-holidays" }
{ "type": "addWorkingDays", "country": "US", "startDate": "2026-12-23", "days": 5, "resultDate": "2026-12-31", "calendarDays": 8, "skippedWeekendDays": 2, "skippedHolidays": [{ "date": "2026-12-25", "name": "Christmas Day" }] }
```

### Use it with

Google Maps or lead scrapers (combine with the opening-hours and country normalizers), AI agents that schedule work, or any Apify task that needs a due date: call this Actor with a batch of queries and read the dataset.

### FAQ

**Which data is used?** Nager.Date (open source holiday API, about 100 countries) when available, otherwise the offline date-holidays database (about 200 countries and many regions, no network). Each row says which.

**Does it use the web?** Only for Nager.Date in `auto`/`nager` mode. `offline` never does.

**Are half days and bridge days included?** No. Only full public and bank holidays count as non-working.

### Honest limits

- Holiday dates for far-future years follow the calendar rules; dates fixed by decree (many Islamic and Chinese holidays) can be off by a day or be missing until announced.
- Weekends are by country, with a small built-in list of Friday-Saturday countries; companies with other schedules should set `weekend`.
- Regional holidays need the exact region code of the data source; unknown regions return only nationwide holidays or an error row.
- City time zones come from an offline list of about 7,000 cities; unknown cities need coordinates.

### Price

Pay per event: **$0.0005 per query answered** (a holiday list for a whole year is one query; failed queries are free). 10,000 queries = $5.

# Actor input Schema

## `operation` (type: `string`):

holidays lists the public holidays of a country and year. addWorkingDays adds (or subtracts) N working days to a date. workingDaysBetween counts working days between two dates. isBusinessDay checks one date. timezone finds the time zone of a city or coordinates.

## `country` (type: `string`):

ISO 3166 country code such as US, GB, FR, DE, TN. For holidays you may give several separated by commas (US,GB,FR). For time zone lookups it only helps to choose between cities with the same name.

## `region` (type: `string`):

Optional state or region code to include regional holidays, for example CA for California, BY for Bavaria, or ENG for England. Leave empty for nationwide holidays only.

## `year` (type: `integer`):

Year for the holiday list. 0 means the current year.

## `date` (type: `string`):

Date as YYYY-MM-DD for addWorkingDays, workingDaysBetween (start) and isBusinessDay. Leave empty for today (UTC).

## `endDate` (type: `string`):

End date as YYYY-MM-DD, only for workingDaysBetween. Both the start and end date are counted. Leave empty for today (UTC).

## `days` (type: `integer`):

Number of working days to add to the start date for addWorkingDays. Negative numbers go back in time.

## `latitude` (type: `string`):

Latitude for the time zone lookup, for example 36.8065. Decimal numbers are typed as text because the input form has no decimal field.

## `longitude` (type: `string`):

Longitude for the time zone lookup, for example 10.1815.

## `city` (type: `string`):

City name for the time zone lookup when no coordinates are given, for example Tunis or Austin. Uses an offline list of about 7,000 cities.

## `queries` (type: `array`):

Optional. A list of queries answered in one run; when filled it replaces the fields above. Each query is an object such as {"op":"addWorkingDays","country":"US","start":"2026-12-23","days":5} or {"op":"holidays","country":"FR","year":2027} or {"op":"timezone","city":"Tunis"}.

## `holidaySource` (type: `string`):

auto uses Nager.Date (about 100 countries, official list) and falls back to the offline date-holidays data (about 200 countries and many regions). nager uses only Nager.Date. offline uses only the built-in data and never calls the web.

## `includeObservances` (type: `boolean`):

When off (default) only public and bank holidays are listed and skipped by the working-day maths. When on, observances and optional holidays (Valentine's Day, Mother's Day...) are included too.

## `weekend` (type: `string`):

Leave empty to use the country's usual weekend (Saturday and Sunday; Friday and Saturday in Saudi Arabia, Egypt, Israel and similar countries). Or list the days, for example sat,sun or fri,sat.

## `maxQueries` (type: `integer`):

Safety limit on the number of queries answered in one run.

## Actor input object example

```json
{
  "operation": "holidays",
  "country": "US",
  "region": "",
  "year": 0,
  "date": "",
  "endDate": "",
  "days": 5,
  "latitude": "",
  "longitude": "",
  "city": "",
  "queries": [],
  "holidaySource": "auto",
  "includeObservances": false,
  "weekend": "",
  "maxQueries": 5000
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `downloadCsv` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `count` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "operation": "holidays",
    "country": "US",
    "region": "",
    "year": 0,
    "date": "",
    "endDate": "",
    "days": 5,
    "latitude": "",
    "longitude": "",
    "city": "",
    "queries": [],
    "holidaySource": "auto",
    "weekend": "",
    "maxQueries": 5000
};

// Run the Actor and wait for it to finish
const run = await client.actor("that_red_bird/business-calendar-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "operation": "holidays",
    "country": "US",
    "region": "",
    "year": 0,
    "date": "",
    "endDate": "",
    "days": 5,
    "latitude": "",
    "longitude": "",
    "city": "",
    "queries": [],
    "holidaySource": "auto",
    "weekend": "",
    "maxQueries": 5000,
}

# Run the Actor and wait for it to finish
run = client.actor("that_red_bird/business-calendar-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "operation": "holidays",
  "country": "US",
  "region": "",
  "year": 0,
  "date": "",
  "endDate": "",
  "days": 5,
  "latitude": "",
  "longitude": "",
  "city": "",
  "queries": [],
  "holidaySource": "auto",
  "weekend": "",
  "maxQueries": 5000
}' |
apify call that_red_bird/business-calendar-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,that_red_bird/business-calendar-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BhphFbkkSh7ea4c45/builds/QB7ykQFuY2sSCoNgc/openapi.json