# 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
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/)