Use Cases & Tutorials

1import { FestivoClient } from '@festivo-io/festivo-sdk';
2
3  async function getNextPayrollDate(country, cityCode, currentDate) {
4    const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY || 'YOUR_API_KEY' });
5    const year = new Date(currentDate).getFullYear();
6    const { holidays } = await client.getHolidays(country, year, { regions: cityCode });
7    const holidayDates = new Set(holidays.map(h => h.observed));
8
9    let nextDate = new Date(currentDate);
10    nextDate.setDate(nextDate.getDate() + 1);
11
12    while (true) {
13      const dateStr = nextDate.toISOString().split('T')[0];
14      const dayOfWeek = nextDate.getDay();
15      if (dayOfWeek !== 0 && dayOfWeek !== 6 && !holidayDates.has(dateStr)) {
16        return nextDate;
17      }
18      nextDate.setDate(nextDate.getDate() + 1);
19    }
20  }
21
22  const nextPayrollDate = await getNextPayrollDate('IT', 'IT-MILAN', '2026-12-06');
23  console.log(`Next payroll date: ${nextPayrollDate.toISOString().split('T')[0]}`);

1import { FestivoClient } from '@festivo-io/festivo-sdk';
2
3async function isRestaurantOperating(cityCode, country, date) {
4const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY || 'YOUR_API_KEY' });
5const year = new Date(date).getFullYear();
6const { holidays } = await client.getHolidays(country, year, { regions: cityCode });
7
8const isCityHoliday = holidays.some(h => {
9  return h.observed === date && h.regions?.some(r => r.type === 'city');
10});
11
12const dayOfWeek = new Date(date).getDay();
13const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
14
15return {
16  operating: !isCityHoliday && !isWeekend,
17  reason: isCityHoliday ? 'City holiday' : isWeekend ? 'Weekend' : 'Operating normally'
18};
19}
20
21const availability = await isRestaurantOperating('IT-MILAN', 'IT', '2026-12-07');
22console.log(availability);

1interface LocalEvent {
2name: string;
3name_local: string;
4date: string;
5type: string;
6description: string;
7}
8
9async function getLocalEvents(
10cityCode: string,
11country: string,
12startDate: string,
13endDate: string
14): Promise<LocalEvent[]> {
15const startYear = new Date(startDate).getFullYear();
16const endYear = new Date(endDate).getFullYear();
17
18const allEvents: LocalEvent[] = [];
19
20// Get holidays for each year in range
21for (let year = startYear; year <= endYear; year++) {
22const response = await fetch(
23`https://api.getfestivo.com/v3/public-holidays/list?country=${country}&regions=${cityCode}&year=${year}&api_key=YOUR_API_KEY`
24);
25
26  const { holidays } = await response.json();
27
28  // Filter to date range and city-specific events
29  const events = holidays
30    .filter(h => h.observed >= startDate && h.observed <= endDate)
31    .filter(h => h.regions?.some(r => r.type === 'city'))
32    .map(h => ({
33      name: h.name,
34      name_local: h.name_local,
35      date: h.observed,
36      type: h.type,
37      description: h.description || ''
38    }));
39
40  allEvents.push(...events);
41
42}
43
44return allEvents;
45}
46
47// Usage: Show tourists what's happening in Rome (IT-ROME)
48const romeEvents = await getLocalEvents("IT-ROME", "IT", "2026-06-01", "2026-06-30");
49console.log(`Local events in Rome during your visit: ${romeEvents.length}`);
50romeEvents.forEach(e => {
51console.log(`${e.date}: ${e.name} (${e.name_local})`);
52});

1def check_compliance(city_code, country, work_dates):
2  """
3  Verify that no work is scheduled on holidays
4  Returns: (is_compliant, violations)
5  """
6  api_key = os.getenv('FESTIVO_API_KEY')
7
8  # Get unique years from work dates
9  years = set(datetime.fromisoformat(d).year for d in work_dates)
10
11  # Get all holidays for those years
12  all_holidays = []
13  for year in years:
14      response = requests.get(
15          "https://api.getfestivo.com/v3/public-holidays/list",
16          params={
17              "country": country,
18              "regions": city_code,
19              "year": year,
20              "api_key": api_key
21          }
22      )
23      all_holidays.extend(response.json()["holidays"])
24
25  # Build set of public holiday dates
26  public_holiday_dates = {
27      h["observed"] for h in all_holidays
28      if h.get("public", False)
29  }
30
31  # Check for violations
32  violations = [date for date in work_dates if date in public_holiday_dates]
33
34  return len(violations) == 0, violations
35
36# Usage: Check employee schedule in Milan (IT-MILAN)
37
38work_schedule = ["2026-12-07", "2026-12-08", "2026-12-25"]
39compliant, violations = check_compliance("IT-MILAN", "IT", work_schedule)
40
41if not compliant:
42print(f"⚠️ Labor law violation: Work scheduled on: {violations}")
43print("Action required: Reschedule or provide holiday compensation")
44else:
45print("✓ Schedule is compliant with local holidays")

1async function getDeliveryDate(destinationCityCode, destinationCountry, orderDate, processingDays) {
2const year = new Date(orderDate).getFullYear();
3
4// Get holidays for destination city
5const response = await fetch(
6`https://api.getfestivo.com/v3/public-holidays/list?country=${destinationCountry}&regions=${destinationCityCode}&year=${year}&api_key=YOUR_API_KEY`
7);
8
9const { holidays } = await response.json();
10const holidayDates = new Set(holidays.map(h => h.observed));
11
12let currentDate = new Date(orderDate);
13let workingDaysAdded = 0;
14
15while (workingDaysAdded < processingDays) {
16currentDate.setDate(currentDate.getDate() + 1);
17const dateStr = currentDate.toISOString().split('T')[0];
18const dayOfWeek = currentDate.getDay();
19
20  // Count only working days (not weekends or holidays)
21  if (dayOfWeek !== 0 && dayOfWeek !== 6 && !holidayDates.has(dateStr)) {
22    workingDaysAdded++;
23  }
24
25}
26
27return currentDate;
28}
29
30// Usage: E-commerce delivery to Milan (IT-MILAN)
31const estimatedDelivery = await getDeliveryDate("IT-MILAN", "IT", "2026-12-04", 3);
32console.log(`Estimated delivery: ${estimatedDelivery.toISOString().split('T')[0]}`);
33// Automatically skips Dec 7 (Saint Ambrose Day)

1interface SettlementResult {
2settlementDate: string;
3businessDays: number;
4holidaysSkipped: string[];
5}
6
7async function calculateSettlementDate(
8country: string,
9tradeDate: string,
10settlementDays: number = 2 // T+2 standard
11): Promise<SettlementResult> {
12const year = new Date(tradeDate).getFullYear();
13
14const response = await fetch(
15`https://api.getfestivo.com/v3/public-holidays/list?country=${country}&year=${year}&type=bank&api_key=YOUR_API_KEY`
16);
17
18const { holidays } = await response.json();
19const bankHolidays = new Set(holidays.map(h => h.observed));
20const skipped: string[] = [];
21
22let current = new Date(tradeDate);
23let businessDaysAdded = 0;
24
25while (businessDaysAdded < settlementDays) {
26current.setDate(current.getDate() + 1);
27const dateStr = current.toISOString().split('T')[0];
28const dayOfWeek = current.getDay();
29
30  if (dayOfWeek !== 0 && dayOfWeek !== 6 && !bankHolidays.has(dateStr)) {
31    businessDaysAdded++;
32  } else if (bankHolidays.has(dateStr)) {
33    skipped.push(dateStr);
34  }
35
36}
37
38return {
39settlementDate: current.toISOString().split('T')[0],
40businessDays: settlementDays,
41holidaysSkipped: skipped
42};
43}
44
45// Usage: Financial transaction in UK
46const settlement = await calculateSettlementDate("GB", "2026-04-02", 2);
47console.log(`Settlement date: ${settlement.settlementDate}`);
48console.log(`Bank holidays skipped: ${settlement.holidaysSkipped.join(', ')}`);

1async function calculateProjectDeadline(country, cityCode, startDate, workingDays) {
2const year = new Date(startDate).getFullYear();
3const nextYear = year + 1;
4
5// Get holidays for current and next year
6const [currentYearHolidays, nextYearHolidays] = await Promise.all([
7fetch(`https://api.getfestivo.com/v3/public-holidays/list?country=${country}&regions=${cityCode}&year=${year}&api_key=YOUR_API_KEY`).then(r => r.json()),
8fetch(`https://api.getfestivo.com/v3/public-holidays/list?country=${country}&regions=${cityCode}&year=${nextYear}&api_key=YOUR_API_KEY`).then(r => r.json())
9]);
10
11const allHolidays = [...currentYearHolidays.holidays, ...nextYearHolidays.holidays];
12const publicHolidays = new Set(
13allHolidays
14  .filter(h => h.public)
15  .map(h => h.observed)
16);
17
18let currentDate = new Date(startDate);
19let workingDaysAdded = 0;
20const timeline = [];
21
22while (workingDaysAdded < workingDays) {
23currentDate.setDate(currentDate.getDate() + 1);
24const dateStr = currentDate.toISOString().split('T')[0];
25const dayOfWeek = currentDate.getDay();
26const isWorkingDay = dayOfWeek !== 0 && dayOfWeek !== 6 && !publicHolidays.has(dateStr);
27
28  timeline.push({
29    date: dateStr,
30    isWorkingDay,
31    reason: publicHolidays.has(dateStr) ? 'Holiday' : !isWorkingDay ? 'Weekend' : 'Working day'
32  });
33
34  if (isWorkingDay) {
35    workingDaysAdded++;
36  }
37
38}
39
40return {
41deadline: timeline[timeline.length - 1].date,
42totalDays: timeline.length,
43workingDays: workingDaysAdded,
44holidaysEncountered: timeline.filter(d => d.reason === 'Holiday').length
45};
46}
47
48// Usage: 20 working-day project in Milan (IT-MILAN)
49const deadline = await calculateProjectDeadline("IT", "IT-MILAN", "2026-11-25", 20);
50console.log(`Project deadline: ${deadline.deadline}`);
51console.log(`Holidays encountered: ${deadline.holidaysEncountered}`);

1const Redis = require('redis');
2const client = Redis.createClient();
3
4async function getHolidaysWithCache(country, regionCode, year) {
5const cacheKey = `holidays:${country}:${regionCode}:${year}`;
6
7// Try cache first
8const cached = await client.get(cacheKey);
9if (cached) {
10return JSON.parse(cached);
11}
12
13// Fetch from API
14const response = await fetch(
15`https://api.getfestivo.com/v3/public-holidays/list?country=${country}&regions=${regionCode}&year=${year}&api_key=YOUR_API_KEY`
16);
17
18const data = await response.json();
19
20// Cache for 24 hours
21await client.setEx(cacheKey, 86400, JSON.stringify(data.holidays));
22
23return data.holidays;
24}
25
26// Usage: Cache key includes region code (IT-MILAN)
27const holidays = await getHolidaysWithCache("IT", "IT-MILAN", 2026);

1import time
2
3def get_holidays_with_retry(country, region_code, year, max_retries=3):
4api_key = os.getenv('FESTIVO_API_KEY')
5url = "https://api.getfestivo.com/v3/public-holidays/list"
6params = {"country": country, "regions": region_code, "year": year, "api_key": api_key}
7
8  for attempt in range(max_retries):
9      try:
10          response = requests.get(url, params=params)
11
12          if response.status_code == 429:
13              # Rate limited - check retry-after header
14              retry_after = int(response.headers.get('Retry-After', 60))
15              print(f"Rate limited. Retrying after {retry_after}s...")
16              time.sleep(retry_after)
17              continue
18
19          response.raise_for_status()
20          return response.json()["holidays"]
21
22      except requests.exceptions.RequestException as e:
23          if attempt == max_retries - 1:
24              raise
25
26          # Exponential backoff
27          wait_time = 2 ** attempt
28          print(f"Attempt {attempt + 1} failed. Retrying in {wait_time}s...")
29          time.sleep(wait_time)
30
31  raise Exception("Max retries exceeded")
32
33# Usage: Region code format is {COUNTRY_CODE}-{CITY}
34
35holidays = get_holidays_with_retry("IT", "IT-MILAN", 2026)