holidays.rest TypeScript SDK

Official TypeScript SDK for the holidays.rest API.

Requirements

• Node.js ≥ 18 (uses native fetch)
• TypeScript 5+ (for consumers using TypeScript)
• Zero runtime dependencies

Installation

npm i @holidays-rest/sdk-ts
# or
yarn add @holidays-rest/sdk-ts

Quick Start

import { HolidaysClient } from "@holidays-rest/sdk-ts";

const client = new HolidaysClient({ apiKey: "YOUR_API_KEY" });

const holidays = await client.getHolidays({ country: "US", year: 2024 });
holidays.forEach((h) => console.log(`${h.date} — ${h.name.en}`));

Get an API key at holidays.rest/dashboard.

---

API

new HolidaysClient(options)

interface ClientOptions {
  apiKey:   string;   // required — Bearer token from dashboard
  baseUrl?: string;   // optional — override for testing
}

---

getHolidays(params) → Promise<Holiday[]>

interface HolidaysParams {
  country:   string;                          // required — ISO 3166 alpha-2 (e.g. "US")
  year:      number | string;                 // required — e.g. 2024

  month?:    number | string;                 // optional — 1–12
  day?:      number | string;                 // optional — 1–31
  type?:     string | string[];               // "religious" | "national" | "local"
  religion?: number | number[];               // religion codes 1–11
  region?:   string | string[];               // subdivision codes from getCountry()
  lang?:     string | string[];               // language codes from getLanguages()
  response?: "json" | "xml" | "yaml" | "csv"; // default: "json"
}

// All US holidays in 2024
await client.getHolidays({ country: "US", year: 2024 });

// National holidays only
await client.getHolidays({ country: "DE", year: 2024, type: "national" });

// Multiple types
await client.getHolidays({ country: "TR", year: 2024, type: ["national", "religious"] });

// Filter by month and day
await client.getHolidays({ country: "GB", year: 2024, month: 12, day: 25 });

// Specific region
await client.getHolidays({ country: "US", year: 2024, region: "US-CA" });

// Multiple regions
await client.getHolidays({ country: "US", year: 2024, region: ["US-CA", "US-NY"] });

---

getCountries() → Promise<Country[]>

const countries = await client.getCountries();
countries.forEach((c) => console.log(`${c.alpha2} — ${c.name}`));

---

getCountry(countryCode) → Promise<Country>

Returns country details including subdivision codes usable as region filters.

const us = await client.getCountry("US");
us.subdivisions?.forEach((s) => console.log(`${s.code} — ${s.name}`));

---

getLanguages() → Promise<Language[]>

const languages = await client.getLanguages();

---

Types

All request and response types are exported:

import type {
  Holiday,
  HolidayDay,
  HolidayName,
  Country,
  Subdivision,
  Language,
  HolidaysParams,
  ClientOptions,
} from "@holidays-rest/sdk-ts";

interface HolidayName {
  [lang: string]: string; // e.g. { en: "New Year's Day", de: "Neujahr" }
}

interface HolidayDay {
  actual:   string; // weekday the holiday falls on, e.g. "Thursday"
  observed: string; // weekday legally observed, e.g. "Monday"
}

interface Holiday {
  country_code: string;   // ISO 3166 alpha-2, e.g. "DE"
  country_name: string;   // e.g. "Germany"
  date:         string;   // ISO 8601, e.g. "2026-01-01"
  name:         HolidayName;
  isNational:   boolean;
  isReligious:  boolean;
  isLocal:      boolean;
  isEstimate:   boolean;
  day:          HolidayDay;
  religion:     string;   // e.g. "Christianity" or ""
  regions:      string[]; // subdivision codes, e.g. ["BW", "BY"], or []
}

interface Country {
  name: string; alpha2: string; subdivisions?: Subdivision[];
}

interface Subdivision { code: string; name: string; }
interface Language    { code: string; name: string; }

---

Error Handling

Non-2xx responses throw HolidaysApiError:

import { HolidaysClient, HolidaysApiError } from "@holidays-rest/sdk-ts";

try {
  await client.getHolidays({ country: "US", year: 2024 });
} catch (err) {
  if (err instanceof HolidaysApiError) {
    console.log(err.status);   // HTTP status code (number)
    console.log(err.message);  // Error message (string)
    console.log(err.body);     // Raw response body (unknown)
  }
}

Status	Meaning
400	Bad request
401	Invalid API key
404	Not found
500	Server error
503	Service unavailable

---

Building

npm run build       # outputs ESM + CJS + .d.ts to dist/
npm run typecheck   # type-check without emitting

The build outputs:

File	Format	Used by
dist/index.js	ESM	import / bundlers
dist/index.cjs	CJS	require() / older tooling
dist/index.d.ts	Types	TypeScript consumers

---

License

MIT