Holiday API Node.js Library

Official Node.js library for Holiday API providing quick and easy access to holiday information from applications written in server-side JavaScript.

Documentation

Full documentation of the Holiday API endpoints is available here.

Installation

# NPM
npm install --save holidayapi

# Yarn
yarn add holidayapi

Usage

import { HolidayAPI } from 'holidayapi';

const key = 'Insert your API key here';
const holidayApi = new HolidayAPI({ key });

// Fetch supported countries and subdivisions
holidayApi.countries()
  .then((countries) => { console.log(countries); })
  .catch((err) => { console.error(err); });

// Fetch supported languages
holidayApi.languages()
  .then((languages) => { console.log(languages); })
  .catch((err) => { console.error(err); });

// Fetch holidays with minimum parameters
holidayApi.holidays({ country: 'US', year: 2019 })
  .then((holidays) => { console.log(holidays); })
  .catch((err) => { console.error(err); });

// Async? Await? No problem!
(async () => {
  // Fetch supported countries and subdivisions
  const countries = await holidayApi.countries();

  // Fetch supported languages
  const languages = await holidayApi.languages();

  // Fetch holidays with minimum parameters
  const holidays = await holidayApi.holidays({
    country: 'US',
    year: 2019,
  });
})();

Examples

Countries

Fetch all supported countries

holidayApi.countries();

Fetch only countries with public holidays

holidayApi.countries({
  public: true,
});

Fetch a supported country by code

holidayApi.countries({
  country: 'NO',
});

Search for countries by code or name

holidayApi.countries({
  search: 'united',
});

Languages

Fetch all supported languages

holidayApi.languages();

Fetch a supported language by code

holidayApi.language({
  language: 'es',
});

Search for languages by code or name

holidayApi.language({
  search: 'Chinese',
});

Holidays

Fetch holidays for a specific year

holidayApi.holidays({
  country: 'US',
  year: 2019,
});

Fetch holidays for a specific month

holidayApi.holidays({
  country: 'US',
  year: 2019,
  month: 7,
});

Fetch holidays for a specific day

holidayApi.holidays({
  country: 'US',
  year: 2019,
  month: 7,
  day: 4,
});

Fetch upcoming holidays based on a specific date

holidayApi.holidays({
  country: 'US',
  year: 2019,
  month: 7,
  day: 4,
  upcoming: true,
});

Fetch previous holidays based on a specific date

holidayApi.holidays({
  country: 'US',
  year: 2019,
  month: 7,
  day: 4,
  previous: true,
});

Fetch only public holidays

holidayApi.holidays({
  country: 'US',
  year: 2019,
  public: true,
});

Fetch holidays for a specific subdivision

holidayApi.holidays({
  country: 'GB-ENG',
  year: 2019,
});

Include subdivision holidays with countrywide holidays

holidayApi.holidays({
  country: 'US',
  year: 2019,
  subdivisions: true,
});

Search for a holiday by name

holidayApi.holidays({
  country: 'US',
  year: 2019,
  search: 'New Year',
});

Translate holidays to another language

holidayApi.holidays({
  country: 'US',
  year: 2019,
  language: 'zh', // Chinese (Simplified)
});

Fetch holidays for multiple countries

holidayApi.holidays({
  country: 'US,GB,NZ',
  year: 2019,
});

holidayApi.holidays({
  country: ['US', 'GB', 'NZ'],
  year: 2019,
});

Workday

Fetch workday 7 business days after a date

holidayApi.workday({
  country: 'US',
  start: '2019-07-01',
  days: 7,
});

Workdays

Fetch number of workdays between two dates

holidayApi.workday({
  country: 'US',
  start: '2019-07-01',
  end: '2019-07-10',
});