🌍 World Holidays

A comprehensive Flutter package providing holiday information for multiple countries (2024-2026). Get holidays for South Korea, United States, Japan, China, Vietnam, Malaysia, Thailand, Canada, Brazil, and Taiwan with automatic online updates and offline fallback support.

✨ Features

🆓 Completely Free - No API keys or costs required
🌐 Always Up-to-Date - Automatically fetches latest holiday data online
📱 Offline Fallback - Works without internet connection using local data
🔄 Smart Caching - Efficient data storage and retrieval
🏳️ Multi-Country - Support for 10 countries with 508 total holidays
🌐 Multilingual - English and Korean descriptions for all holidays
📅 3-Year Coverage - Holiday data for 2024, 2025, and 2026
⚡ Fast & Lightweight - Minimal dependencies and optimized performance

🏳️ Supported Countries

Country	Code	Holidays	Flag
South Korea	`KR`	41 holidays	🇰🇷
United States	`US`	32 holidays	🇺🇸
Japan	`JP`	57 holidays	🇯🇵
China	`CN`	72 holidays	🇨🇳
Vietnam	`VN`	44 holidays	🇻🇳
Malaysia	`MY`	44 holidays	🇲🇾
Thailand	`TH`	61 holidays	🇹🇭
Canada	`CA`	33 holidays	🇨🇦
Brazil	`BR`	51 holidays	🇧🇷
Taiwan	`TW`	57 holidays	🇹🇼

📦 Installation

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

dependencies:
  world_holidays: ^2.0.0

Then run:

flutter pub get

🚀 Quick Start

import 'package:world_holidays/world_holidays.dart';

void main() async {
  final worldHolidays = WorldHolidays();

  // Get holidays for South Korea (fetches latest data online)
  final holidays = await worldHolidays.getHolidays('KR');
  print('Found ${holidays.length} holidays');

  // Check if today is a holiday
  final isToday = worldHolidays.isTodayHoliday('KR');
  print('Is today a holiday? $isToday');

  // Get next upcoming holiday
  final nextHoliday = worldHolidays.getNextHoliday('KR');
  if (nextHoliday != null) {
    print('Next holiday: ${nextHoliday.name} on ${nextHoliday.dateString}');
  }
}

📖 Detailed Usage

Getting Holidays

final worldHolidays = WorldHolidays();

// Get all holidays for a country (automatically fetches latest data online)
final allHolidays = await worldHolidays.getHolidays('KR');

// Get holidays for a specific year (online data with offline fallback)
final holidays2025 = await worldHolidays.getHolidays('KR', year: 2025);

// Get holidays for different countries
final usHolidays = await worldHolidays.getHolidays('US');
final jpHolidays = await worldHolidays.getHolidays('JP');
final cnHolidays = await worldHolidays.getHolidays('CN');
final thHolidays = await worldHolidays.getHolidays('TH');
final brHolidays = await worldHolidays.getHolidays('BR');

Manual Data Updates (Optional)

The library automatically fetches the latest data online. Use these methods only if you need to force updates:

// Force update specific country (downloads 3-year data)
await worldHolidays.updateHolidays(countryCode: 'KR');

// Force update all supported countries
await worldHolidays.updateHolidays();

📡 Online vs Offline Usage

Default Behavior (Online-First):

// Automatically fetches latest data from GitHub Pages API
final holidays = await worldHolidays.getHolidays('KR');

Offline-Only Usage: If you want to use only local data without internet requests, disable automatic updates:

// For offline-only applications, use local fallback data
// Note: This requires manual cache management
await worldHolidays.clearCache(); // Clear any cached online data
final offlineHolidays = await worldHolidays.getHolidays('KR');
// Will use local hardcoded data when no internet/cache available

Best Practice: Let the library handle online/offline automatically - it will use online data when available and fall back to local data when offline.

Checking Holidays

// Check if a specific date is a holiday
final isHoliday = worldHolidays.isHoliday('KR', DateTime(2024, 1, 1));

// Check if today is a holiday
final isTodayHoliday = worldHolidays.isTodayHoliday('US');

// Get the next upcoming holiday
final nextHoliday = worldHolidays.getNextHoliday('JP');

// Get holidays in a date range
final rangeHolidays = worldHolidays.getHolidaysInRange(
  'KR',
  DateTime(2024, 1, 1),
  DateTime(2024, 12, 31),
);

Multilingual Support

All holidays now include multilingual descriptions in English and Korean:

final holidays = await worldHolidays.getHolidays('KR');
final holiday = holidays.first;

// Get description in specific language
print(holiday.getDescription('en')); // "New Year's Day"
print(holiday.getDescription('ko')); // "신정"

// Convenience getters
print(holiday.descriptionEn); // "New Year's Day"
print(holiday.descriptionKo); // "신정"

// Access raw description object
print(holiday.description); // {"en": "New Year's Day", "ko": "신정"}

Utility Methods

// Get supported countries
final countries = worldHolidays.getSupportedCountries();
print(countries); // ['BR', 'CA', 'CN', 'JP', 'KR', 'MY', 'TH', 'TW', 'US', 'VN']

// Get supported years
final years = worldHolidays.getSupportedYears();
print(years); // [2024, 2025, 2026]

// Clear cached data
await worldHolidays.clearCache();

📱 Example App

Check out the example app for a complete Flutter application demonstrating all features.

🔧 Holiday Types

The package categorizes holidays into different types:

NATIONAL - Official national public holidays
RELIGIOUS - Religious observances and holidays
REGIONAL - Regional or state-specific holidays
OBSERVANCE - Cultural observances and commemorative days

🌐 Data Source

Holiday data is sourced from:

GitHub Pages API - Real-time updates via https://beomq.github.io/world_holidays/api/
Local Fallback - Embedded data for offline usage (508 holidays across 10 countries)
Official Sources - Government and cultural organization websites
Multilingual Support - English and Korean descriptions for all holidays

🔄 Update Strategy

API Updates - Immediate for urgent holiday changes
Library Updates - Quarterly for new years and major changes
Data Accuracy - Verified against official government sources

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Adding New Countries

Research official holidays from government sources
Create JSON data file with 3-year coverage
Add local fallback data to the library
Update tests and documentation
Submit PR with detailed information

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Holiday data sourced from official government websites
Built with ❤️ for the Flutter community
Inspired by the need for accurate, free holiday data

📞 Support

📧 Issues: GitHub Issues
📖 Documentation: GitHub Pages
💬 Discussions: GitHub Discussions

Made with 🌍 by beomq