Public Holiday Calendar By Country

Public Holiday Calendar By Country helps payroll teams, logistics operators, finance operations teams, workforce planners, and automation developers apply country holiday calendars and business-day rules to their own CSV, JSON, or Excel records. Every successful record comes back as one flat, import-ready row that keeps your opaque record ID and a source reference, so it joins straight back into your payroll, shipping, invoicing, or reporting system.

What it does

• Reads inline records, pasted CSV or JSON, base64 CSV/JSON, and genuine XLSX workbook bytes. Optionally downloads a document over HTTPS from apify.com or date.nager.at.
• Flags Saturday/Sunday weekends and public holidays on the original date, with holiday names.
• Applies an adjustment convention (none, next, previous, nearest) and then a signed business-day offset from -366 to 366.
• Offline mode works with built-in US federal holiday rules (including weekend observance) or with complete country-year calendars that you supply. Online mode (holidaySource: nager) uses the public Nager.Date API, one request per country-year, cached during the run, with retries.
• Accepts only unambiguous ISO dates (YYYY-MM-DD). Values such as 03/04/2025 are rejected with INVALID_DATE instead of being guessed.
• Reports problems per record: successful rows go to the dataset, failed records are listed with an error code and a retryable flag in the OUTPUT record. One bad row never aborts the batch.
• Optionally writes a CSV or XLSX RESULTS file with the successful rows.

How to use it

The prefilled input runs without any network access. Copy this into the Actor input:

{
  "inputMode": "records",
  "holidaySource": "offline",
  "records": [
    { "recordId": "invoice-1042", "countryCode": "US", "date": "2025-07-04", "adjustmentConvention": "next", "businessDayOffset": 0 },
    { "recordId": "shipment-208", "countryCode": "US", "date": "2025-07-03", "adjustmentConvention": "none", "businessDayOffset": 2 }
  ],
  "outputFormat": "json"
}

For CSV use inputMode: text with format: csv; for Excel use inputMode: base64 with format: xlsx and real workbook bytes (one worksheet, headers in row 1). Required columns: recordId, countryCode, date; optional: regionCode, adjustmentConvention, businessDayOffset. Header names are matched case-insensitively and ignore spaces, underscores and hyphens (Record ID works). Unknown columns are rejected per row, so remove unrelated export columns first. Formula cells are not evaluated and fail their row.

Supplying your own calendar: each offlineCalendars entry has countryCode, year, complete: true, regionCodes, and holidays (date, name, optional regionCode). The Actor trusts your completeness declaration. If you supply a country, include every year a calculation might enter; a missing year fails the row rather than falling back.

Output example

recordId	inputDate	isPublicHoliday	adjustedDate	calendarDaysShifted	sourceRef
invoice-1042	2025-07-04	true	2025-07-07	3	input:records#row=1
shipment-208	2025-07-03	false	2025-07-08	5	input:records#row=2

Each dataset row also has rowNumber, status (always ok), country and region, weekday, weekend flag, holiday names, adjustment settings, businessDaysShifted, source attribution, and warnings. Holiday flags describe the original date. OUTPUT contains rows, failures, summary, and an outcome block (status, counts, limit flag).

Pricing

Pay per event. The main charge is per adjusted record; everything else listed below is free.

Event	Price (USD)	Charged when
Adjusted record (apify-default-dataset-item)	$0.002	A successful result row is pushed to the default dataset. Failed rows, summaries and manifests are never charged.

Not charged:

• OUTPUT.failures
• OUTPUT.summary
• OUTPUT.outcome
• RESULTS export

Examples (default 512 MB memory, one start event):

• 100 valid records: 100 × $0.002 = $0.20
• 10,000 valid records: 10000 × $0.002 = $20.00

Spending limit: when you set a maximum cost per run, the Actor stops before it would exceed it, keeps every adjusted record it already delivered and reports limitReached in the OUTPUT record. It never delivers results beyond the limit.

The Store's Pricing tab shows the prices in force. If this section and the Pricing tab ever differ, the Pricing tab applies.

Use cases

• Flag payments and reporting deadlines that fall on public holidays.
• Move shipment and contract dates to the next, previous, or nearest working day.
• Compute business-day lead times with positive or negative offsets.
• Annotate multi-country CSV, Excel, or JSON records before a database import.
• Re-run repeatable checks against an internally approved calendar.

Limits

• 1-1,000 records per run; decoded documents up to 25 MiB; JSON nesting up to 8 levels.
• Dates must be real ISO dates from 2020 to 2035.
• At most 50 distinct country-year calendars per run; each search examines at most 1,100 calendar days.
• Weekends are always Saturday and Sunday. Built-in offline rules cover US federal holidays only; other countries need your own calendar or the Nager source. Nager.Date coverage and observed-date conventions depend on that service.
• A region is accepted only if the calendar explicitly covers it; without a region only national holidays apply (a warning is added when regional data exists).
• Requests time out after 10 seconds, follow at most 3 validated redirects, and the run has a 120-second processing budget.

FAQ

Does offline mode use the internet?

No. Inline records, text, and base64 documents with the offline source make no document or holiday requests.

What happens if some rows are invalid?

They are listed in OUTPUT.failures with a row number, source reference, error code, and message. Valid rows continue. If no row succeeds, the run fails after writing OUTPUT. Set failOnAnyError to also fail the run when any row failed (successful rows are still published).

How is nearest calculated?

The closest working day wins; on a tie the following day is chosen. The offset then counts working days starting from the adjusted date, not counting the start date.

What if the holiday service is down?

Affected rows fail with SOURCE_UNAVAILABLE and retryable: true. Empty or malformed upstream data is never treated as a holiday-free calendar.

Are my files stored?

The Actor writes no extra copy of your documents and logs no source rows. Apify input and output storage follows your account settings, so use opaque IDs.