world_holidays 2.1.2

Generated multi-country holiday information with offline-first lookup and optional hosted updates.

World Holidays

Generated holiday data for Flutter applications, with bundled offline lookup and optional hosted updates.

Live calendar and hosted API · API metadata · Issue tracker

Coverage

Version 2.1.2 contains 842 records for 2024-2028.

Country	Code	Records
South Korea	KR	99
United States	US	62
Japan	JP	90
China	CN	120
Vietnam	VN	73
Malaysia	MY	73
Thailand	TH	111
Canada	CA	45
Brazil	BR	71
Taiwan	TW	98

Future dates can change after government announcements. Treat generated future records as planning data and apply reviewed overrides for temporary or substitute holidays.

Hosted API

The same generated records are published through GitHub Pages:

https://beomq.github.io/world_holidays/api/countries.json
https://beomq.github.io/world_holidays/api/holidays/kr.json

Country metadata includes the canonical dataUrl for every supported payload. The live calendar consumes these files directly.

Installation

dependencies:
  world_holidays: ^2.1.2

import 'package:world_holidays/world_holidays.dart';

Basic lookup

final worldHolidays = WorldHolidays();

// Fresh seven-day cache first, then bundled generated data.
final koreanHolidays = await worldHolidays.getHolidays('KR', year: 2027);

final newYear = worldHolidays.isHoliday('KR', DateTime(2027, 1, 1));
final nextBundled = worldHolidays.getNextHoliday('JP');

getHolidays() does not make a network request automatically. Networking is always explicit through an update method.

Explicit hosted updates

Use structured outcomes when the caller needs to distinguish remote success from bundled fallback.

final outcome = await worldHolidays.updateCountryHolidays('KR');

if (outcome.succeeded) {
  print('Downloaded ${outcome.holidays.length} records');
} else {
  print('Using ${outcome.source}: ${outcome.error}');
}

final bulk = await worldHolidays.updateAllHolidays();
print('Updated: ${bulk.successfulCountries}');
print('Fallback: ${bulk.failedCountries}');

A bulk update attempts every supported country. One failed country no longer aborts later updates. updateHolidays() remains as a compatibility adapter that returns only the flattened holiday list.

Cache-aware queries

The original synchronous query methods remain deterministic and use bundled data. Use their asynchronous counterparts after an online update.

await worldHolidays.updateCountryHolidays('US');

final isHoliday = await worldHolidays.isHolidayAsync(
  'US',
  DateTime(2027, 7, 5),
);
final next = await worldHolidays.getNextHolidayAsync('US');
final today = await worldHolidays.isTodayHolidayAsync('US');

Inclusive date ranges are also cache-aware:

final holidays = await worldHolidays.getHolidaysInRange(
  'KR',
  DateTime(2027, 1, 1),
  DateTime(2027, 12, 31),
);

Passing an end date before the start date throws ArgumentError.

Holiday model

Descriptions use an English/Korean map:

final holiday = koreanHolidays.first;
print(holiday.descriptionEn);
print(holiday.descriptionKo);
print(holiday.getDescription('ko'));

Legacy JSON string descriptions still decode as English. Unknown holiday type wire values throw FormatException instead of silently becoming national holidays. Returned lists and descriptions decoded by the package are immutable.

Cache behavior

• SharedPreferences key: world_holidays_<lowercase-country-code>
• Expiry: seven days
• Cached payload: complete country response; year/range filtering happens when read
• Expired, malformed, or invalid-type cache entries fall back to bundled data
• clearCache() removes all package cache entries

Data generation

The project does not scrape or republish a third-party holiday portal. It runs the MIT-licensed python-holidays library locally and combines calculated years with reviewed project data.

• api/holidays/*.json: hosted payloads and reviewed curated years
• data/overrides.json: curated-year ownership, corrections, removals, upserts
• lib/src/generated/holiday_data.g.dart: generated bundled lookup data
• api/countries.json: generated counts and supported years

# Generate previous year, current year, and the following two years.
uv run --no-project tool/sync_holidays.py

# Verify checked-in outputs without changing the repository.
uv run --no-project tool/sync_holidays.py --check

# Reproduce a specific horizon.
uv run --no-project tool/sync_holidays.py --current-year 2026

Existing curated historical years are retained. Non-curated years are rebuilt from the installed python-holidays version on every synchronization.

Recommended operation:

• Weekly synchronization throughout the year
• Review data/curated-drift.json for calculated dates missing from curated years
• Manual workflow dispatch after temporary-holiday announcements
• Review every generated pull request before publishing

Development

fvm flutter pub get
fvm dart format --output=none --set-exit-if-changed \
  lib/world_holidays.dart lib/src/models lib/src/world_holidays.dart test example
fvm flutter analyze --no-pub
fvm flutter test --no-pub
uv run --no-project tool/sync_holidays.py --check
fvm flutter pub publish --dry-run

Upgrading from 2.1.1

Version 2.1.2 changes holiday data only. No Dart API migration is required.

fvm flutter pub upgrade world_holidays

• Synchronous isHoliday() and getNextHoliday() calls use corrected bundled data after the package upgrade.
• Cache-aware callers can apply the hosted correction immediately with await worldHolidays.updateCountryHolidays('KR').
• getHolidays() still does not access the network automatically. Without an explicit update, an existing cached payload remains valid for up to seven days before bundled data is used. Call clearCache() when corrected bundled data must be used immediately without relying on the network.

The Korean corrections remove the false 2024-09-19 and 2025-01-31 substitute holidays and add the official 2025-01-27 temporary public holiday.

Migrating from 2.0.x

See the 2.0.1 to 2.1.2 migration guide for the complete compatibility and rollout checklist.

The main 2.0.1 lookup and update signatures remain source-compatible. Review immutable package results, strict unknown-type parsing, cache rollout, and service disposal before upgrading.

License

This package is released under the MIT License. Generated baseline dates use the MIT-licensed python-holidays project; reviewed corrections remain in this repository.