{"id":37022250,"url":"https://github.com/focus-shift/jollyday","last_synced_at":"2026-04-04T21:03:55.613Z","repository":{"id":37935360,"uuid":"475804152","full_name":"focus-shift/jollyday","owner":"focus-shift","description":"Jollyday - A worldwide public holidays library","archived":false,"fork":false,"pushed_at":"2026-01-12T15:23:54.000Z","size":5237,"stargazers_count":109,"open_issues_count":20,"forks_count":27,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-12T20:55:43.315Z","etag":null,"topics":["bank-holidays","calculate-holidays","calendar","hacktoberfest","holiday","holiday-api","holidayapi","holidays","java","public-holiday-calender","public-holidays","publicholidays"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/focus-shift.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"focus-shift"}},"created_at":"2022-03-30T09:15:20.000Z","updated_at":"2026-01-12T15:23:58.000Z","dependencies_parsed_at":"2025-04-22T20:22:33.357Z","dependency_job_id":"aad8083d-17ea-4173-b669-3f20cc0e2bc9","html_url":"https://github.com/focus-shift/jollyday","commit_stats":null,"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/focus-shift/jollyday","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-shift%2Fjollyday","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-shift%2Fjollyday/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-shift%2Fjollyday/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-shift%2Fjollyday/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/focus-shift","download_url":"https://codeload.github.com/focus-shift/jollyday/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/focus-shift%2Fjollyday/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bank-holidays","calculate-holidays","calendar","hacktoberfest","holiday","holiday-api","holidayapi","holidays","java","public-holiday-calender","public-holidays","publicholidays"],"created_at":"2026-01-14T02:39:04.457Z","updated_at":"2026-04-04T21:03:55.575Z","avatar_url":"https://github.com/focus-shift.png","language":"Java","readme":"# Jollyday [![Build Status](https://github.com/focus-shift/jollyday/actions/workflows/build.yml/badge.svg)](https://github.com/focus-shift/jollyday/actions/workflows/build.yml) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=focus-shift_jollyday\u0026metric=coverage)](https://sonarcloud.io/summary/overall?id=focus-shift_jollyday) [![Maven Central](https://img.shields.io/maven-central/v/de.focus-shift/jollyday-core.svg)](https://central.sonatype.com/artifact/de.focus-shift/jollyday-core/) [![Javadocs](https://www.javadoc.io/badge/de.focus-shift/jollyday-core.svg)](https://www.javadoc.io/doc/de.focus-shift/jollyday-core)\n\nJollyday is a Java library to query public holidays. Currently, we support **over 100 countries**.\n\n_Note_: the `main` branch contains the 2.x release line of Jollyday. The legacy `1.x` branch continues the 1.x line is available at [1.x](https://github.com/focus-shift/jollyday/tree/1.x). A migration guide for upgrading to 2.0 is available in the project wiki: [Jollyday 2.0 Migration Guide](https://github.com/focus-shift/jollyday/wiki/Jollyday-2.0-Migration-Guide).\n\n\u003cimg src=\".docs/world.svg\" style=\"max-width:800px; width:100%;\" alt=\"World map with countries colored in blue that are supported by jollyday\"/\u003e\n\n## How to use it\n\n**Jollyday** is based on **Java 17** and can be used directly as dependency via maven or Gradle e.g.\nThe calculation basis of the public holidays for each country is based on an XML file and will be mapped via Jakarta XML Binding or Jackson.\nIf you already use one of these libraries in your project than just use the specific jollyday dependency.\n\n\u003cdetails\u003e\n  \u003csummary\u003eMaven (click to expand)\u003c/summary\u003e\n\n  You need the core library, that defines all functionality and the api for you as developer.\n\n  ```xml\n  \u003cdependency\u003e\n    \u003cgroupId\u003ede.focus-shift\u003c/groupId\u003e\n    \u003cartifactId\u003ejollyday-core\u003c/artifactId\u003e\n    \u003cversion\u003e${version}\u003c/version\u003e\n  \u003c/dependency\u003e\n  ```\n\n  ### XML-Binding libraries\n\n  Additionally, the XML-Binding library of your choice. At the moment we do support JAXB and Jackson,\n  but in the future there could be more that these.\n\n  **Jakarta XML Binding (JAXB)**\n\n  ```xml\n  \u003cdependency\u003e\n    \u003cgroupId\u003ede.focus-shift\u003c/groupId\u003e\n    \u003cartifactId\u003ejollyday-jaxb\u003c/artifactId\u003e\n    \u003cversion\u003e${version}\u003c/version\u003e\n  \u003c/dependency\u003e\n  ```\n\n  **Jackson**\n\n  ```xml\n  \u003cdependency\u003e\n    \u003cgroupId\u003ede.focus-shift\u003c/groupId\u003e\n    \u003cartifactId\u003ejollyday-jackson\u003c/artifactId\u003e\n    \u003cversion\u003e${version}\u003c/version\u003e\n  \u003c/dependency\u003e\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eGradle (click to expand)\u003c/summary\u003e\n\n  You need the core library, that defines all functionality and the api for you as developer.\n\n  ```gradle\n  implementation group: 'de.focus-shift', name: 'jollyday-core', version: '${version}'\n  ```\n\n  ### XML-Binding libraries\n\n  Additionally, the XML-Binding library of your choice. At the moment we do support JAXB and Jackson,\n  but in the future there could be more that these.\n\n  **Jakarta XML Binding (JAXB)**\n\n  ```gradle\n  implementation group: 'de.focus-shift', name: 'jollyday-jaxb', version: '${version}'\n  ```\n\n  **Jackson**\n\n  ```gradle\n  implementation group: 'de.focus-shift', name: 'jollyday-jackson', version: '${version}'\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003ewith the Java Platform Module System (click to expand)\u003c/summary\u003e\n\n  If you want to use Jollyday in a project that is modularized via java modules you need to require the `de.focus_shift.jollyday.core` module via\n  \n  ```java\n  module your.application {\n    ...\n    requires de.focus_shift.jollyday.core;\n    ...\n  }\n```\n\u003c/details\u003e\n\n### Examples\n\n\u003cdetails\u003e\n  \u003csummary\u003eRetrieve public holidays for a year (click to expand)\u003c/summary\u003e\n\nReturns all **german** public holidays in **2022**\n  ```java\n  import de.focus_shift.jollyday.core.Holiday;\n  import de.focus_shift.jollyday.core.HolidayManager;\n  import de.focus_shift.jollyday.core.ManagerParameters;\n\n  import java.util.Set;\n\n  import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;\n\n  final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));\n  final Set\u003cHoliday\u003e holidays = holidayManager.getHolidays(Year.of(2022));\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRetrieve public holidays for a period of days (click to expand)\u003c/summary\u003e\n\nReturns all german public holidays from the **15th of april in 2022** until the **31st of may in 2023**\n  ```java\n  import de.focus_shift.jollyday.core.Holiday;\n  import de.focus_shift.jollyday.core.HolidayManager;\n  import de.focus_shift.jollyday.core.ManagerParameters;\n\n  import java.time.LocalDate;\n  import java.util.Set;\n\n  import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;\n\n  final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));\n  final Set\u003cHoliday\u003e holidays = holidayManager.getHolidays(LocalDate.of(2022, 4, 15), LocalDate.of(2023, 5, 31));\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCheck if a specific date is a public holiday (click to expand)\u003c/summary\u003e\n\nReturns true or false if a date is a public holidays in Germany.\n  ```java\n  import de.focus_shift.jollyday.core.HolidayManager;\n  import de.focus_shift.jollyday.core.ManagerParameters;\n\n  import java.time.LocalDate;\n\n  import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;\n\n  final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));\n  final boolean isHoliday = holidayManager.isHoliday(LocalDate.of(2022, 6, 6));\n  ```\n\nReturns true or false if a date is a public holidays in Baden-Württemberg in Germany.\n  ```java\n  import de.focus_shift.jollyday.core.HolidayManager;\n  import de.focus_shift.jollyday.core.ManagerParameters;\n\n  import java.time.LocalDate;\n\n  import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;\n\n  final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));\n  final boolean isHoliday = holidayManager.isHoliday(LocalDate.of(2022, 6, 6), \"bw\");\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eOverride an existing country (click to expand)\u003c/summary\u003e\n\nIf you want to override the public holidays of a provided country like **Germany**, you need to put a holiday file\nunder the path `holidays/` and name it `Holidays_de.xml` on your classpath. Jollyday will pick up yours at first.\nThe file and the hierarchy need to be identical to the one you want to override.\n\nThe holiday file structure needs to look like the one below. The XML Schema Definition file can be viewed [here](jollyday-core/src/main/resources/focus_shift.de/jollyday/schema/holiday/holiday.xsd)\n\n  ```xml\n  \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n  \n  \u003cConfiguration hierarchy=\"de\" description=\"Germany\"\n                 xmlns=\"https://focus_shift.de/jollyday/schema/holiday\"\n                 xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n                 xsi:schemaLocation=\"https://focus_shift.de/jollyday/schema/holiday https://focus_shift.de/jollyday/schema/holiday/holiday.xsd\"\u003e\n    \u003cHolidays\u003e\n      \u003c!-- Add the holidays here--\u003e\n    \u003c/Holidays\u003e\n  \n    ...\n    \n    \u003cSubConfigurations hierarchy=\"bw\" description=\"Baden-Württemberg\"\u003e\n      \u003cHolidays\u003e\n      ...\n      \u003c/Holidays\u003e\n    \u003c/SubConfigurations\u003e\n  \u003c/Configuration\u003e\n  ```\n\u003c/details\u003e\n\n### Configuration\n\n#### Providing own configuration\n\nThe configuration resides within the `jollyday.properties` and can be overridden or added:\n\n\u003cdetails\u003e\n  \u003csummary\u003evia ManagerParameter (click to expand)\u003c/summary\u003e\n\n  ```java\n    import de.focus_shift.jollyday.core.Holiday;\n    import de.focus_shift.jollyday.core.HolidayManager;\n    import de.focus_shift.jollyday.core.ManagerParameters;\n    import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;\n    \n    final ManagerParameter managerParameter = ManagerParameters.create(GERMANY);\n    managerParameter.setProperty(\"manager.impl\", \"de.focus_shift.jollyday.core.impl.SpecialHolidayManager\");\n  ```\n  \n  The `ManagerParameters` can be used to add new or override existing configuration.\n\n  This will override the **via own Configuration Provider Classes**, **via own jollyday.properties** and the **via url** specified configurations.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003evia own Configuration Provider Classes (click to expand)\u003c/summary\u003e\n\n  Providing a comma separated list of **classes** through the system property `de.focus_shift.jollyday.config.providers`\n  which implement the `ConfigurationProvider` interface.\n\n  This will override the **via own jollyday.properties** and the **via url** specified configurations.\n\n  ```bash\n  -Dde.focus_shift.jollyday.config.providers=some.package.name.MyConfigurationProvider,some.other.package.AnotherConfigurationProvider\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003evia url (click to expand)\u003c/summary\u003e\n\n  Providing a comma separated list of **urls** through the system property `de.focus_shift.jollyday.config.urls` which point\n  to configuration files.\n\n  This will override the **via own jollyday.properties** specified configurations.\n\n  ```bash\n  -Dde.focus_shift.jollyday.config.urls=file:/some/path/new.properties,http://myserver/some/path/further.properties,jar:file:myLibrary.jar!/my.properties\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003evia own `jollyday.properties` (click to expand)\u003c/summary\u003e\n\n  You can define your own `jollyday.properties` in your classpath, e.g. in a spring boot application in the ressource directory.\n\n  This will override the base `jollyday.properties` provided by jollyday itself.\n\u003c/details\u003e\n\n#### Providing own implementations\n\n\u003cdetails\u003e\n  \u003csummary\u003eof Holiday Manager (click to expand)\u003c/summary\u003e\n  A manager implementation extends the abstract `HolidayManager` class and does the actual holiday parsing.\n  The basic API properties are used to define the manager implementation class used for the specific\n  country the manager is created for.\n  \n  ```properties\n  manager.impl=de.focus_shift.jollyday.core.impl.DefaultHolidayManager\n  ```\n  \n  This configuration defines a manager implementation class used as a default for every country. You can define a\n  manager implementation on a per country base.\n  \n  ```properties\n  manager.impl=de.focus_shift.jollyday.core.impl.XMLManager\n  manager.impl.us=de.focus_shift.jollyday.core.impl.MyXMLManager\n  ```\n\n  This will let the `MyXMLManager` class be used for calculating US holidays and the `XMLManager` for all other countries.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eof Holiday Parser (click to expand)\u003c/summary\u003e\n\n  A parser implementation is used for parsing the XML file content. There are several parsers configured depending on the class to parse the info from.\n  \n  ```properties\n  parser.impl.de.focus_shift.jollyday.core.spi.FixedHolidayConfiguration                       = de.focus_shift.jollyday.core.parser.impl.FixedParser\n  parser.impl.de.focus_shift.jollyday.core.spi.FixedWeekdayInMonthHolidayConfiguration         = de.focus_shift.jollyday.core.parser.impl.FixedWeekdayInMonthParser\n  parser.impl.de.focus_shift.jollyday.core.spi.IslamicHolidayConfiguration                     = de.focus_shift.jollyday.core.parser.impl.IslamicHolidayParser\n  parser.impl.de.focus_shift.jollyday.core.spi.ChristianHolidayConfiguration                   = de.focus_shift.jollyday.core.parser.impl.ChristianHolidayParser\n  parser.impl.de.focus_shift.jollyday.core.spi.RelativeToFixedHolidayConfiguration             = de.focus_shift.jollyday.core.parser.impl.RelativeToFixedParser\n  parser.impl.de.focus_shift.jollyday.core.spi.RelativeToWeekdayInMonthHolidayConfiguration    = de.focus_shift.jollyday.core.parser.impl.RelativeToWeekdayInMonthParser\n  parser.impl.de.focus_shift.jollyday.core.spi.FixedWeekdayBetweenFixedHolidayConfiguration    = de.focus_shift.jollyday.core.parser.impl.FixedWeekdayBetweenFixedParser\n  parser.impl.de.focus_shift.jollyday.core.spi.FixedWeekdayRelativeToFixedHolidayConfiguration = de.focus_shift.jollyday.core.parser.impl.FixedWeekdayRelativeToFixedParser\n  parser.impl.de.focus_shift.jollyday.core.spi.EthiopianOrthodoxHolidayConfiguration           = de.focus_shift.jollyday.core.parser.impl.EthiopianOrthodoxHolidayParser\n  parser.impl.de.focus_shift.jollyday.core.spi.RelativeToEasterSundayHolidayConfiguration      = de.focus_shift.jollyday.core.parser.impl.RelativeToEasterSundayParser\n  ```\n\n  The configuration property name starts with `parser.impl` and finishes with the XML class name.\n  The value is the parser implementation class name which implements the `HolidayParser` interface. \n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eof Configuration Service (click to expand)\u003c/summary\u003e\n  A configuration service implementation is used to define which XML unmarshalling implementation should be used\n\n  ```properties\n  configuration.service.impl = de.focus_shift.jollyday.jackson.JacksonConfigurationService\n  ```\n\n  The configuration property `configuration.service.impl` contains the class name as string.\n  The value is the configuration service implementation class name which implements the `HolidayCalendarConfigurationService` interface.\n\n  Values are:\n  * `de.focus_shift.jollyday.jackson.JacksonConfigurationService` (default)\n  * `de.focus_shift.jollyday.jaxb.JaxbConfigurationService`\n\n\u003c/details\u003e\n\n## ISO 3166\n\nTo retrieve the public holidays of a country the [ISO 3166-1 alpha-2] standard is used. A [list of current ISO 3166-1 alpha-2 codes] is available at wikipedia.\n\nTo access the public holidays of a subdivision of a country, e.g. Baden-Württemberg of Germany the [ISO 3166-2] standard is used. A [list of current ISO 3166-2 codes] is available at wikipedia.\n\n### Data precision\n\n| Precision                      | Supported |\n|--------------------------------|-----------|\n| Country ([ISO 3166-1 alpha-2]) | Yes       |\n| Subdivisions ([ISO 3166-2])    | Yes       |\n| City Holiday                   | Yes       |\n\n## Holiday types\n\nThe following holiday types are supported:\n\n**Public Holiday**  \nPublic holidays are days when most of the public enjoys a paid non-working days. These days are determined by local laws\nand regulations. Countries use various names for these official non-working days, such as:\n\n| Other Names for Public Holiday | Country          | Businesses |\n|--------------------------------|------------------|------------|\n| Bank Holiday                   | United Kingdom   | Closed     |\n| National Holiday               | Most Countries   | Closed     |\n| Red Days                       | Norway           | Closed     |\n| Regular Holidays               | Philippines      | Closed     |\n| Restricted Holidays            | India            | Closed     |\n| Statutory Holiday              | Canada           | Closed     |\n\nWe will declare all of these as **Public Holiday**\n\n**Bank Holiday**  \nBank holidays are days when financial institutions and government offices (and government-regulated businesses)\nare closed as determined by local laws and regulations. Other businesses, such as offices and retail stores,\nmay also be closed on these days, though are not mandated to by local laws and regulations.\n\n**Observance**  \nObservance, is a celebration or commemoration that doesn't include a day off from work. When people celebrate or\ncommemorate something, but do not have a day off from work for that reason, we call it an observance.\nThere are different types of observance like Religious, Secular, Awareness, International or National observance.\nWe will declare all of these as **Observance**\n\n## Development\n\nIf you want to **support** us at the development on **jollyday** than take a look at [Contributing to jollyday](./CONTRIBUTING.md).\nIf you have any kind of **questions** please go to [Discussions] and see if there are already answers and if not please open a discussion with your question. \nIf you want to raise an **issue or bug** you can create a [new issue](https://github.com/focus-shift/jollyday/issues/new/choose)\n\n### Requirements\n\n* [JDK 17](https://openjdk.java.net/install/)\n\n### Architecture decision record (ADR)\n\n* [Subdivisions with Their Own ISO 3166-1 Alpha-2 Codes as Separate Files](.adr/002-subdivision-with-own-iso-3166-1-alpha-2.md)\n* [Document empty subdivision](.adr/001-document-every-subdivision.md)\n\n### git hooks (optional)\n\nThere are some app specific git hooks to automate stuff like:\n\n* Add 'closes #issue-number' to the commit message\n\nIf you want to take advantage of this automation you can run:\n\n```bash\ngit config core.hooksPath '.githooks' \n```\n\nThe git hooks can be found in the [.githooks](./.githooks/) directory.\n\n## License\n\n[Apache License, Version 2.0](LICENSE)\n\n[Discussions]: https://github.com/focus-shift/jollyday/discussions\n[ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2\n[list of current ISO 3166-1 alpha-2 codes]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes\n[ISO 3166-2]: https://en.wikipedia.org/wiki/ISO_3166-2\n[list of current ISO 3166-2 codes]: https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes\n","funding_links":["https://github.com/sponsors/focus-shift"],"categories":["Projects"],"sub_categories":["Date and Time"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffocus-shift%2Fjollyday","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffocus-shift%2Fjollyday","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffocus-shift%2Fjollyday/lists"}