2017-02-02 02:37:43 +00:00
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< meta http-equiv = "X-UA-Compatible" content = "IE=edge" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
<!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
< title > holiday-api Documentation< / title >
<!-- Bootstrap -->
< link rel = "stylesheet" href = "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap-theme.min.css"
integrity="sha256-ZT4HPpdCOt2lvDkXokHuhJfdOKSPFLzeAJik5U/Q+l4=" crossorigin="anonymous" />
< link rel = "stylesheet" href = "https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/superhero/bootstrap.min.css"
integrity="sha256-LEplvgQTKatd65f2Z/JThrYx/sdoKygi0dsC1h5sInE=" crossorigin="anonymous" />
2017-02-02 11:01:08 +00:00
< link rel = "stylesheet" href = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/styles/solarized-dark.min.css"
integrity="sha256-90Y+fvi28WF+3jKH4tHEkoQ9WLeFKJjpvCPNOtU9ZvU=" crossorigin="anonymous" />
2017-02-02 02:37:43 +00:00
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!-- [if lt IE 9]>
< script src = "https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"
integrity="sha256-3Jy/GbSLrg0o9y5Z5n1uw0qxZECH7C6OQpVBgNFYa0g=" crossorigin="anonymous">< / script >
< script src = "https://cdnjs.cloudflare.com/ajax/libs/respond.js/1.4.2/respond.min.js"
integrity="sha256-g6iAfvZp+nDQ2TdTR/VVKJf3bGro4ub5fvWSWVRi2NE=" crossorigin="anonymous">< / script >
<![endif]-->
< / head >
< body >
< div class = "container" >
< div class = "col-md-12" id = "display" >
# 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
2017-02-02 10:17:58 +00:00
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
2017-02-02 02:37:43 +00:00
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)
2017-02-02 10:17:58 +00:00
- [`/de-by/2017/10`](/de-by/2017/10) - Holidays for Bavaria for October 2017
2017-02-02 02:37:43 +00:00
2021-12-27 03:56:57 +00:00
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
2021-12-27 04:15:48 +00:00
- [`/de-by/2017.ics?locale=de`](/de-by/2017.ics?locale=de) - Holidays for Bavaria for October 2017 in ICS format using German holiday names
2021-12-27 03:56:57 +00:00
2017-02-02 02:37:43 +00:00
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
2017-02-02 10:17:58 +00:00
- `HTTP 404` if your URL is invalid.
2017-02-02 02:37:43 +00:00
- `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
[
2017-02-02 11:01:08 +00:00
{
"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"
}
2017-02-02 02:37:43 +00:00
]
```
## 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/)
< / div >
< / div >
< a href = "https://github.com/Luzifer/go-holidays" class = "github-corner" aria-label = "View source on Github" > < svg width = "80" height = "80" viewBox = "0 0 250 250" style = "fill:#70B7FD; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden = "true" > < path d = "M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z" > < / path > < path d = "M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill = "currentColor" style = "transform-origin: 130px 106px;" class = "octo-arm" > < / path > < path d = "M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill = "currentColor" class = "octo-body" > < / path > < / svg > < / a > < style > . github-corner : hover . octo-arm { animation : octocat-wave 560 ms ease-in-out } @ keyframes octocat-wave { 0 % , 100 % { transform : rotate ( 0 ) } 20 % , 60 % { transform : rotate ( -25 deg ) } 40 % , 80 % { transform : rotate ( 10 deg ) } } @ media ( max-width : 500px ) { . github-corner : hover . octo-arm { animation : none } . github-corner . octo-arm { animation : octocat-wave 560 ms ease-in-out } } < / style >
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
< script src = "https://cdnjs.cloudflare.com/ajax/libs/jquery/1.12.4/jquery.min.js"
integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous">< / script >
<!-- Include all compiled plugins (below), or include individual files as needed -->
< script src = "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js"
integrity="sha256-U5ZEeKfGNOja007MMD3YBI0A3OSZOQbeG6z2f2Y0hu8=" crossorigin="anonymous">< / script >
< script src = "https://cdnjs.cloudflare.com/ajax/libs/marked/0.3.6/marked.min.js"
integrity="sha256-mJAzKDq6kSoKqZKnA6UNLtPaIj8zT2mFnWu/GSouhgQ=" crossorigin="anonymous">< / script >
2017-02-02 11:01:08 +00:00
< script src = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/highlight.min.js"
integrity="sha256-KbfTjB0WZ8vvXngdpJGY3Yp3xKk+tttbqClO11anCIU=" crossorigin="anonymous">< / script >
2017-02-02 02:37:43 +00:00
< script >
2017-02-02 11:01:08 +00:00
marked.setOptions({
highlight: function (code) { return hljs.highlightAuto(code).value },
});
$(function(){
$('#display').html(marked($('#display').html()));
});
2017-02-02 02:37:43 +00:00
< / script >
< / body >
< / html >
