ApiToll

← Catalog

Holidays.

Public and observance holidays for 203 countries, any year. Optional filter by holiday type. $0.001 per call.

Endpoint
GET /v1/holidays/:iso2/:year
Optional
?type=public,bank,school,observance,optional
Price
0.001 USDC per successful call
Source
date-holidays open-source dataset
License
ISC
Coverage
203 countries, year range 1900-2100
Auth
None. x402 payment is the auth.

Try the sandbox →   Same response shape, test USDC on Base Sepolia. Get a test wallet drip.

What you get

JSON. Same shape on every call.

{
  "status":  "success",
  "country": "US",
  "year":    2026,
  "count":   23,
  "holidays": [
    { "date": "2026-01-01", "name": "New Year's Day",            "type": "public",     "substitute": false },
    { "date": "2026-01-19", "name": "Martin Luther King Jr. Day", "type": "public",     "substitute": false },
    { "date": "2026-02-14", "name": "Valentine's Day",           "type": "observance", "substitute": false },
    { "date": "2026-07-04", "name": "Independence Day",           "type": "public",     "substitute": false },
    { "date": "2026-12-25", "name": "Christmas Day",              "type": "public",     "substitute": false }
  ],
  "meta": { "source": "date-holidays open-source dataset", "source_license": "ISC" }
}

Why pay

Public sources exist. Hosting them is the work.

  1. The dataset is open. Maintaining it is the cost.

    date-holidays ships ~100 contributors' worth of country-specific rules. We host the latest, refresh it, and serve it. You get the answer.

  2. Free alternatives are rate-limited and require signup.

    Nager.Date public API caps the free tier. Hosting your own copy means tracking a moving target. ApiToll handles both.

  3. Filter at the edge.

    ?type=public to drop observances. ?type=bank,school for scheduling. Saves you parsing the full list when you only want bank holidays.

Use cases

What agents do with this.

  1. Booking and scheduling agents.

    "Can the meeting be on this date?" — check the country's public holidays before proposing.

  2. Payroll and HR.

    Compute working days between two dates with country-specific holidays subtracted.

  3. E-commerce.

    Adjust shipping ETAs around national holidays. Trigger holiday-themed promotions on the right dates per region.

  4. Compliance.

    SLA timers that pause on bank holidays. Court / filing deadlines that respect the relevant jurisdiction's calendar.

Honest framing

What it is not.

Good for: public holidays, bank holidays, observances, school holidays, any country your agent operates in.

Not good for:

  • Religious calendars at sub-country granularity (e.g. specific Jewish or Islamic observances by community)
  • Future legislative changes (the dataset reflects current law; future-year predictions can shift)
  • Substitute / observed-on dates for everywhere — the substitute flag is set where the dataset has it; not all countries are covered

Try it

Right now.

One line to see the 402 challenge (no wallet needed):

curl -i https://apitoll.io/v1/holidays/US/2026

When you're ready to actually pay, send a signed X-PAYMENT header (most agent SDKs do this for you). See the agent primer for full setup. Or hit the sandbox first.

Discovery

Pricing rationale

$0.001 per call. Holiday lookups are bursty — an agent typically needs the full year list once and caches. Low cost makes it a no-brainer integration.