Public Holidays Lookup Data Connector

The Public Holidays Lookup Data Connector provides access to the Nager.Date Public Holidays API. This Data Connector can be used to retrieve the dates and details of public holidays for a given country and year. No authentication is required for this API.

Constructor

PublicHolidays() → {object}

A Public Holidays Lookup Data Connector is available at connectors.verjio.publicholidays.

You may also use this constructor to create a new Public Holidays Lookup Data Connector.

Returns:

object

The Public Holiday Lookup Data Connector.

Functions

getAvailableCountries() → {Array.<object>}

Retrieves a list of countries that can be used with the API.

Returns:

Array.<object>

Array of objects containing country details.

Example:

// Create a static list, for a drop down, using available countries
const list = fields.country.createCustomList();

const countries = connectors.verjio.publicholidays.getAvailableCountries(); 
countries.forEach(country => {
  list.add(country.name, country.countryCode);
});

getHolidays(country, yearopt) → (nullable) {object}

Retrieves the public holidays for a specified country and year.

Parameters:

Name	Type	Attributes	Description
country	`string`		Country to retrieve holidays for. The country is specified as a 2-digit ISO code.
year	`integer`	<optional>	Optional year to retrieve holidays for. Defaults to the current year.

Returns:

object

API response object containing public holiday information. Returns null if the country was omitted.

Example:

// Get holidays for the current year for a selected country
const holidays = connectors.verjio.publicholidays.getHolidays(fields.country.value);

// Add holidays to table
tables.holidays.resetTable();
holidays.forEach(holiday => {
  tables.holidays.insertRow();
  tables.holidays.date.value = holiday.date;
  tables.holidays.name.value = holiday.localName;
});

getLongWeekends(country, yearopt) → (nullable) {object}

Retrieves the long weekends for a specified country and year.

A long weeked is a a weekend of three or more days, usually due to a public holiday immediately before or after.

Parameters:

Name	Type	Attributes	Description
country	`string`		Country to retrieve long weekends for. The country is specified as a 2-letter (3166-1 alpha-2) ISO code.
year	`integer`	<optional>	Optional year to retrieve long weekends for. Defaults to the current year.

Returns:

object

API response object containing long weekend information. Returns null if the country was omitted.

Example:

// Get long weekends for a specific country and year
const longWeekends = connectors.verjio.publicholidays.getLongWeekends('US', 2020);

getNext(countryopt) → {object}

Retrieves the next public holiday for a specified country or globally.

Parameters:

Name	Type	Attributes	Description
country	`string`	<optional>	Optional country to retrieve holiday for. The country is specified as a 2-letter (3166-1 alpha-2) ISO code. Defaults to global.

Returns:

object

API response object containing public holiday information.

Example:

// Get the next public holiday for a specific country
const nextHoliday = connectors.verjio.publicholidays.getNext('GB');

event.owner.addInfoMessage(`The next public holiday is ${nextHoliday.localName} on ${nextHoliday.date}!`);

getUpcoming(countryopt) → {object}

Retrieves upcoming public holidays for a specified country or globally.

The public holidays for the next 12 months will be returned.

Parameters:

Name	Type	Attributes	Description
country	`string`	<optional>	Optional country to retrieve holidays for. The country is specified as a 2-letter (3166-1 alpha-2) ISO code. Defaults to global.

Returns:

object

API response object containing public holiday information.

Examples:

// Get upcoming holidays for a specific country
const holidays = connectors.verjio.publicholidays.getUpcoming('GB');

// Get worldwide upcoming
const holidays = connectors.verjio.publicholidays.getUpcoming();

handleError(response)

Checks an API response for errors. If an error is encountered, the appropriate Error is thrown.

Parameters:

Name	Type	Description
response	`object`	The response from a `services.rest` request.

Throws:

HttpRequestError

Thrown when the year is not supported or another parameter is invalid.
HttpNotFoundError

Thrown when the country code is not recognised or the requested endpoint is not found.
HttpServerError

Thrown when the API responded with a server error.

Example:

try {
  connectors.verjio.publicholidays.getHolidays(fields.country.value);
}
catch (e) {
  if (e instanceof HttpNotFoundError) {
    event.owner.addErrorMessage('The country you entered is not supported.');
  }
}

isHoliday(date, country) → {boolean}

Determines if the specified date is a public holiday in the specified country.

Parameters:

Name	Type	Description
date	`object`	Date to check. Specified as a JavaScript Date.
country	`string`	Country to check public holidays for. The country is specified as a 2-letter (3166-1 alpha-2) ISO code.

Returns:

boolean

true if it is a public holiday, false otherwise. Returns false if the date or country were omitted.

isHolidayToday(country) → {boolean}

Determines if today is a public holiday in the specified country.

Parameters:

Name	Type	Description
country	`string`	Country to check public holidays for. The country is specified as a 2-letter (3166-1 alpha-2) ISO code.

Returns:

boolean

true if it is a public holiday, false otherwise. Returns false if the country was omitted.

Example:

if (connectors.verjio.publicholidays.isHolidayToday('GB')) {
	  event.owner.addErrorMessage(`We are closed today due to a public holiday.`);
}