# holiday-api Documentation This instance of `holiday-api` is a convenient wrapper around my [go-holiday library](https://github.com/Luzifer/go-holidays) which contains holidays for different countries. With this wrapper you can request a JSON output for a specific country or state within a country using [ISO 3166-1 alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). For some countries (for example Germany) the corresponding state code extension is supported. ## Usage The supported URL scheme is `/{country-code}/{year}/{month}/{day}`: - `{country-code}` **(required)** - ISO 3166-1 alpha-2 country code - `{year}` _(optional)_ - If not set the current year is used - `{month}` _(optional)_ - If specified list is filtered for given month - `{day}` _(optional)_ - If specified list is filtered for given day Examples: - [`/us`](/us) - Federal holidays for the United States for the current year - [`/de/2017`](/de/2017) - National holidays in Germany for 2017 - [`/de-by/2017`](/de-by/2017) - Holidays for Bavaria for 2017 (Uses [ISO 3166-2:DE](https://en.wikipedia.org/wiki/ISO_3166-2:DE) codes) - [`/de-by/2017/10`](/de-by/2017/10) - Holidays for Bavaria for October 2017 You can also request a specific response format (one of `ics` or `json`): - [`/us.ics`](/us.ics) - Federal holidays for the United States for the current year in ICS format - [`/de-by/2017.ics`](/de-by/2017.ics) - Holidays for Bavaria for October 2017 in ICS format No request limits are enforced so please play nice with the API. ## Response The API will respond with - `HTTP 200` and a JSON array if the query was successful - `HTTP 404` if your URL is invalid. - `HTTP 500` if the requested country-code is not included / supported ### JSON format Each entry consists of four keys: - `name`: Name of the holiday in English language - `localized_name`: A mapping of different localizations (key is an ISO 3166-1 alpha-2 country code) - `date`: A string representation of the date in `YYYY-MM-DD` notation - `parsed_date`: The date as a DateTime string with timezone of the server running the API ```json [ { "name": "New Year's Day", "localized_name": { "de": "Neujahrstag" }, "date": "2017-01-01", "parsed_date": "2017-01-01T00:00:00Z" }, { "name": "Good Friday", "localized_name": { "de": "Karfreitag" }, "date": "2017-04-14", "parsed_date": "2017-04-14T00:00:00Z" } ] ``` ## Contributions If you are fluent in writing Go and know about holidays of a country not yet available inside the library please get in touch with me. Either using an issue or a pull-request in the [repository](https://github.com/Luzifer/go-holidays) or using any method on my website: [ahlers.me](https://ahlers.me/)