Build a holiday calendar and calculate working dates

What you’ll make

A holiday spreadsheet you can filter by country and year, plus separate calculation results for working-day ranges, shifted dates, or service deadlines. You’ll need an Apify account and a spreadsheet app. Each run uses one mode; keep the different output shapes in separate sheets.

1. Export a public holiday calendar

Open Business Days & Public Holidays on Apify and paste this into the JSON input.

{
  "mode": "holidays",
  "countries": [
    "US"
  ],
  "years": [
    2026,
    2027
  ],
  "types": [
    "public"
  ],
  "maxItems": 100
}

Use two-letter country codes such as US, GB, or DE. The explicit years stay the same on repeat runs; update them when planning another year. Omitting years uses the current year. types: ["public"] selects public holidays, and language can request localized names.

For a regional calendar, add a subdivision such as "region": "US-TX". Use one country per regional run because the region applies to every country listed. Review current pricing and set a maximum charge. maxItems caps delivered rows; reaching a cap can leave your calendar incomplete.

2. Make the holiday sheet useful

When the run succeeds, inspect the output and export CSV or Excel. In Google Sheets, choose File → Import → Upload. Keep country, region, year, date, name, localName, types, and global.

Sort by country and date, and keep a note of the run date. Do not remove rows just because two holidays share a date. Check the run log and row limit before treating the export as a full calendar. A public-holiday calendar may differ from your company’s actual days off.

3. Count business days between two dates

Use a separate run with businessDaysBetween. This example requests one calculation for the US and one for Germany.

{
  "mode": "businessDaysBetween",
  "countries": [
    "US",
    "DE"
  ],
  "ranges": [
    {
      "start": "2026-10-01",
      "end": "2026-11-01"
    }
  ],
  "maxItems": 10
}

The start date is included and the end date is excluded. Using November 1 as the end counts the dates in October. Each country/range pair produces one row with start, end, totalDays, businessDays, weekendCount, and holidayCount.

The three counts add up to totalDays. A holiday on a weekend is counted in weekendCount, not counted again in holidayCount. The calculation uses the country’s calendar; listing holidays with another types filter does not customize these calculations.

4. Move a date by working days

Use addBusinessDays for a date a set number of working days before or after a starting date.

{
  "mode": "addBusinessDays",
  "countries": [
    "US"
  ],
  "dates": [
    "2026-12-24"
  ],
  "days": 5,
  "maxItems": 10
}

Read resultDate alongside startDate and days. The output also includes weekendDaysSkipped and holidaysSkipped. Use a negative, nonzero days value to move backward, and add more dates to calculate several results in the same run.

Keep the country and region with each result. A date calculated for one location may differ from the date calculated for another, even with the same starting date and offset.

5. Calculate a deadline in working hours

For an hourly service window, use sla with an explicit start timestamp and working hours. This example requests two working hours from 16:00 in Germany’s Bavaria region.

{
  "mode": "sla",
  "countries": [
    "DE"
  ],
  "region": "DE-BY",
  "starts": [
    "2026-10-05T16:00:00+02:00"
  ],
  "offset": 2,
  "unit": "hours",
  "dayStart": "09:00",
  "dayEnd": "17:00",
  "maxItems": 10
}

The calculation counts hours inside the working window and carries remaining time into the next working period, skipping weekends and public holidays. Read deadline with start, offset, unit, dayStart, and dayEnd. Without explicit hours, the window defaults to 09:00–17:00.

Every start must include Z or a numeric UTC offset. Working hours use that fixed offset; the calculation does not automatically adjust for daylight-saving changes. Use the intended local offset when preparing inputs and review any deadline that crosses a clock change. Overnight working windows are not supported.

6. Refresh and reuse your calendar

Save each configuration as its own Apify task. For holiday refreshes, replace the corresponding country/year sheet after checking the output, rather than appending duplicate calendars. Scheduling a task repeats its saved dates and years; it does not advance explicitly supplied values.

The actor uses Nager.Date and date-holidays data. Its documentation marks coverage for India, Thailand, Malaysia, Trinidad and Tobago, and the Cayman Islands as partial. Check the relevant official calendar and your organization’s rules before using results for contractual deadlines.

If a run fails or looks incomplete

Check country and region codes, date formats, and the fields required by your chosen mode. ranges is for counting days, dates is for shifting dates, and starts is for SLA timestamps. Use positive maxItems, nonzero days, and a positive integer SLA offset.

Check for row or spending limits before accepting a partial export. If a holiday appears to be missing, open an issue on the actor’s Apify page with the country, region, and date.