Country Holiday Library #

A Dart library for accessing holiday data from Google Calendar's public holiday calendars. Built following clean architecture principles with global coverage of 100+ countries.

Features #

• ✅ 100+ Countries: Comprehensive global coverage across all continents
• ✅ Clean Architecture: Domain, Data, and Use Case layers
• ✅ Real-time Data: Always up-to-date holidays from Google Calendar API
• ✅ Type-Safe: Full null safety support
• ✅ Simple API: Easy-to-use facade pattern
• ✅ Well-Tested: Comprehensive test coverage

Installation #

1. Add Dependency #

Add this to your package's pubspec.yaml file:

dependencies:
  country_holiday: ^0.0.1

Then run:

dart pub get

2. Get Google Calendar API Key #

You need a Google Calendar API key to use this library:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Navigate to "APIs & Services" → "Library"
   • Search for "Google Calendar API"
   • Click "Enable"
4. Create credentials:
   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "API Key"
   • Copy your API key
5. (Optional) Restrict your API key:
   • Click on your API key to edit it
   • Under "API restrictions", select "Restrict key"
   • Choose "Google Calendar API"
   • Save changes

Usage #

Basic Example #

import 'package:country_holiday/country_holiday.dart';

void main() async {
  // Initialize with your Google Calendar API key
  const apiKey = 'YOUR_GOOGLE_API_KEY_HERE';
  final countryHolidays = CountryHolidays(apiKey: apiKey);

  // Get all holidays for a country
  final usHolidays = await countryHolidays.getHolidaysByCountry('US');
  print('US has ${usHolidays.length} holidays');

  // Check if a specific date is a holiday
  final isHoliday = await countryHolidays.isHoliday('US', DateTime(2025, 7, 4));
  print('Is July 4th a US holiday? $isHoliday'); // true

  // Get all available countries
  final countries = await countryHolidays.getAllCountries();
  print('${countries.length} countries available');
}

Advanced Usage #

// Get holidays on a specific date
final christmas = DateTime(2025, 12, 25);
final holidays = await countryHolidays.getHolidaysByDate('US', christmas);
print(holidays.first.name); // "Christmas"

// Filter by holiday type
final usHolidays = await countryHolidays.getHolidaysByCountry('US');
final nationalHolidays = usHolidays
    .where((h) => h.type == HolidayType.national)
    .toList();

// Access holiday details
for (var holiday in usHolidays) {
  print('${holiday.name} - ${holiday.date}');
  print('Type: ${holiday.type}');
  print('Public: ${holiday.isPublic}');
  if (holiday.description != null) {
    print('Description: ${holiday.description}');
  }
}

Supported Countries #

The library supports 100+ countries worldwide via Google Calendar's public holiday calendars:

🌎 Americas (20 countries) #

North America: 🇺🇸 US, 🇨🇦 CA, 🇲🇽 MX

Central America & Caribbean: 🇨🇷 CR, 🇵🇦 PA, 🇩🇴 DO, 🇬🇹 GT, 🇭🇳 HN, 🇳🇮 NI, 🇸🇻 SV

South America: 🇦🇷 AR, 🇧🇷 BR, 🇨🇱 CL, 🇨🇴 CO, 🇵🇪 PE, 🇻🇪 VE, 🇪🇨 EC, 🇺🇾 UY, 🇧🇴 BO, 🇵🇾 PY

🌍 Europe (33 countries) #

Western Europe: 🇬🇧 GB, 🇮🇪 IE, 🇫🇷 FR, 🇩🇪 DE, 🇳🇱 NL, 🇧🇪 BE, 🇱🇺 LU, 🇨🇭 CH, 🇦🇹 AT

Southern Europe: 🇪🇸 ES, 🇵🇹 PT, 🇮🇹 IT, 🇬🇷 GR, 🇭🇷 HR, 🇸🇮 SI

Northern Europe: 🇸🇪 SE, 🇳🇴 NO, 🇩🇰 DK, 🇫🇮 FI, 🇮🇸 IS

Eastern Europe: 🇵🇱 PL, 🇨🇿 CZ, 🇸🇰 SK, 🇭🇺 HU, 🇷🇴 RO, 🇧🇬 BG, 🇺🇦 UA, 🇷🇺 RU, 🇱🇹 LT, 🇱🇻 LV, 🇪🇪 EE, 🇷🇸 RS

🌏 Asia (21 countries) #

East Asia: 🇨🇳 CN, 🇯🇵 JP, 🇰🇷 KR, 🇹🇼 TW, 🇭🇰 HK, 🇲🇴 MO

Southeast Asia: 🇹🇭 TH, 🇻🇳 VN, 🇵🇭 PH, 🇮🇩 ID, 🇲🇾 MY, 🇸🇬 SG, 🇱🇦 LA

South Asia: 🇮🇳 IN, 🇵🇰 PK, 🇧🇩 BD, 🇱🇰 LK

Central Asia: 🇰🇿 KZ, 🇺🇿 UZ

🕌 Middle East (11 countries) #

🇮🇱 IL, 🇸🇦 SA, 🇦🇪 AE, 🇶🇦 QA, 🇰🇼 KW, 🇧🇭 BH, 🇴🇲 OM, 🇯🇴 JO, 🇱🇧 LB, 🇹🇷 TR, 🇮🇷 IR

🌍 Africa (12 countries) #

North Africa: 🇪🇬 EG, 🇲🇦 MA, 🇹🇳 TN, 🇩🇿 DZ, 🇱🇾 LY

Sub-Saharan Africa: 🇿🇦 ZA, 🇳🇬 NG, 🇰🇪 KE, 🇬🇭 GH, 🇪🇹 ET, 🇹🇿 TZ, 🇺🇬 UG

🌏 Oceania (4 countries) #

🇦🇺 AU, 🇳🇿 NZ, 🇫🇯 FJ, 🇵🇬 PG

Total: 100+ countries across all continents with real-time holiday data from Google Calendar.

Architecture #

This library follows Clean Architecture principles:

┌─────────────────────────────────────┐
│         Public API (Facade)         │
├─────────────────────────────────────┤
│           Use Cases Layer           │
│  (Business Logic & Validation)      │
├─────────────────────────────────────┤
│          Domain Layer               │
│  (Entities, Enums, Interfaces)      │
├─────────────────────────────────────┤
│           Data Layer                │
│  (Models, Data Sources, Repos)      │
└─────────────────────────────────────┘

Key Principles #

• Dependency Inversion: Domain layer has no dependencies
• Single Responsibility: Each country in its own file
• Open/Closed: Easy to extend without modifying existing code
• DRY: No code duplication

API Reference #

CountryHolidays #

Main facade for accessing holiday data.

Constructor

CountryHolidays({required String apiKey})

Requires a valid Google Calendar API key.

Methods

getHolidaysByCountry

Future<List<Holiday>> getHolidaysByCountry(String countryCode, {int? year})

Get all holidays for a country.

• countryCode: ISO 3166-1 alpha-2 code (e.g., 'US', 'AR', 'BR')
• year: Optional. If not provided, returns current year's holidays
• Returns: List of holidays sorted by date

Example:

// Current year
final holidays = await countryHolidays.getHolidaysByCountry('US');

// Specific year
final holidays2026 = await countryHolidays.getHolidaysByCountry('AR', year: 2026);

getHolidaysByMonth

Future<List<Holiday>> getHolidaysByMonth(String countryCode, int year, int month)

Get holidays for a specific month.

• countryCode: ISO 3166-1 alpha-2 code
• year: Year to query
• month: Month (1-12) to query
• Returns: List of holidays in that month

Example:

// Get December 2026 holidays in Argentina
final decemberHolidays = await countryHolidays.getHolidaysByMonth('AR', 2026, 12);

getHolidaysByDate

Future<List<Holiday>> getHolidaysByDate(String countryCode, DateTime date)

Get holidays on a specific date.

• countryCode: ISO 3166-1 alpha-2 code
• date: Date to check (time component ignored)
• Returns: List of holidays on that date (empty if none)

Example:

final christmas = DateTime(2025, 12, 25);
final holidays = await countryHolidays.getHolidaysByDate('US', christmas);

isHoliday

Future<bool> isHoliday(String countryCode, DateTime date)

Check if a date is a holiday.

• countryCode: ISO 3166-1 alpha-2 code
• date: Date to check (time component ignored)
• Returns: true if at least one holiday exists on that date

Example:

final isHoliday = await countryHolidays.isHoliday('US', DateTime(2025, 7, 4));
print(isHoliday); // true (Independence Day)

getAllCountries

Future<List<Country>> getAllCountries()

Get all available countries.

• Returns: List of 100+ countries sorted by country code

Example:

final countries = await countryHolidays.getAllCountries();
print('${countries.length} countries available');

Holiday Entity #

class Holiday {
  final String name;
  final DateTime date;
  final String? description;
  final bool isPublic;
  final HolidayType type;
}

HolidayType Enum #

enum HolidayType {
  national,    // National/Independence days
  religious,   // Religious holidays
  observance,  // Observance days
  cultural,    // Cultural celebrations
}

Country Entity #

class Country {
  final String code;  // ISO 3166-1 alpha-2
  final String name;  // Full country name
}

Contributing #

Adding Support for a New Country #

To add support for a new country's Google Calendar:

1. Find the Google Calendar ID for the country's public holidays
2. Add the mapping to lib/src/data/datasources/calendar_config.dart:

const Map<String, String> countryToCalendarId = {
  // ... existing countries
  'MX': 'es.mexican#[email protected]',
};

3. Add the country name mapping in google_calendar_data_source.dart:

const countryNames = {
  // ... existing countries
  'MX': 'Mexico',
};

4. Run tests to verify:

dart test

Development #

Running Tests #

dart test

Running the Example #

dart run example/example.dart

Code Analysis #

dart analyze

License #

This project is open source and available under the Apache License 2.0.

Roadmap #

• ✅ Google Calendar API integration
• ✅ Support for 100+ countries worldwide
• ✅ Query holidays by year
• ✅ Query holidays by month
• ✅ Automatic deduplication of holidays
• ✅ Environment variable support
• ❌ Caching mechanism to reduce API calls
• ❌ Regional/state-specific holidays
• ❌ Offline mode with cached data
• ❌ Rate limiting and quota management

Credits #

Built with ❤️ using Dart, clean architecture principles, and Google Calendar API.

Holiday data provided by Google Calendar's public holiday calendars.