For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.holidays.rest/holidays-rest-api/llms.txt. For full documentation content, see https://docs.holidays.rest/holidays-rest-api/llms-full.txt. # holidays GET https://api.holidays.rest/v1/holidays This endpoint retrieves all bank and public holidays for a specific country and year. > 🎗️ The holidays endpoint supports the query parameters in various combinations. Each of these optional parameters can be chained together to filter the results flexibly. See the below combining multiple filters section for more details. > 🎗️ The majority of the query parameters accept multiple values in a comma-separated way. ## Examples - Filter out holidays for a specific type (e.g. national): `?country=DE&year=2024&type=national` - Filter out holidays for multiple types (e.g. local or religious): `?country=DE&year=2024&type=local,religious` - Filter out holidays for a specific religion: `?country=BA&year=2024&religion=2` - Filter out holidays for multiple religions: `?country=BA&year=2024&religion=1,2` - Filter out holidays for a specific region: `?country=BA&year=2024®ion=BIH` - Filter out holidays for multiple regions: `?country=BA&year=2024®ion=BIH,SRP` - Fetch localized holiday names in a specific language: `?country=AT&year=2024&lang=de` - Fetch localized holiday names in multiple languages: `?country=AT&year=2024&lang=de,en,tr` ## Combining Multiple Filters The holidays endpoint supports combining multiple filters to retrieve more complex queries. All the query string parameters that were listed above can be chained together to filter the results flexibly. For example to fetch "local" holidays for "Christianity" in "June" in "BIH" region of Bosnia and Herzegovina as "xml" and in "German" and "Japanese" languages, a query string would be as follows: ``` ?country=BA &year=2024 &month=6 &type=local ®ion=BIH &religion=2 &response=xml &lang=de,ja ``` ## Holiday Concepts Most of our customers only focus on government/bank holidays. In order to obtain these, your best option is to filter holidays using either `national` or `local` parameter. If any of these is `true`, it's very likely that government offices and banks will be closed in a given country. `religious` parameter is typically very useful to identify religious holidays, which in some countries, can be specific to certain religious groups. Unless a `religious` holiday has either `national` or `local` attribute also set to `true`, it will very likely be an optional holiday for certain religious groups, or no holiday at all. ## Religion codes | Code | Religion | | --- | --- | | 1 | Christianity | | 2 | Islam | | 3 | Buddhism | | 4 | Confucianism | | 5 | Hinduism | | 6 | Jainism | | 7 | Judaism | | 8 | Sikhism | | 9 | Yazidism | | 10 | Zoroastrianism | | 11 | Baha-i Faith | Reference: https://docs.holidays.rest/holidays-rest-api/holidays ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: collection version: 1.0.0 paths: /v1/holidays: get: operationId: holidays summary: holidays description: "This endpoint retrieves all bank and public holidays for a specific country and year.\n\n> 🎗️ The holidays endpoint supports the query parameters in various combinations. Each of these optional parameters can be chained together to filter the results flexibly. See the below combining multiple filters section for more details. \n \n> 🎗️ The majority of the query parameters accept multiple values in a comma-separated way. \n \n\n## Examples\n\n- Filter out holidays for a specific type (e.g. national): \n `?country=DE&year=2024&type=national`\n \n\n- Filter out holidays for multiple types (e.g. local or religious): \n `?country=DE&year=2024&type=local,religious`\n \n\n- Filter out holidays for a specific religion: \n `?country=BA&year=2024&religion=2`\n \n\n- Filter out holidays for multiple religions: \n `?country=BA&year=2024&religion=1,2`\n \n\n- Filter out holidays for a specific region: \n `?country=BA&year=2024®ion=BIH`\n \n\n- Filter out holidays for multiple regions: \n `?country=BA&year=2024®ion=BIH,SRP`\n \n\n- Fetch localized holiday names in a specific language: \n `?country=AT&year=2024&lang=de`\n \n\n- Fetch localized holiday names in multiple languages: \n `?country=AT&year=2024&lang=de,en,tr`\n \n\n## Combining Multiple Filters\n\nThe holidays endpoint supports combining multiple filters to retrieve more complex queries. All the query string parameters that were listed above can be chained together to filter the results flexibly. For example to fetch \"local\" holidays for \"Christianity\" in \"June\" in \"BIH\" region of Bosnia and Herzegovina as \"xml\" and in \"German\" and \"Japanese\" languages, a query string would be as follows:\n\n```\n?country=BA\n&year=2024\n&month=6\n&type=local\n®ion=BIH\n&religion=2\n&response=xml\n&lang=de,ja\n```\n\n## Holiday Concepts\n\nMost of our customers only focus on government/bank holidays. In order to obtain these, your best option is to filter holidays using either\_`national`\_or\_`local`\_parameter. If any of these is\_`true`, it's very likely that government offices and banks will be closed in a given country.\n\n`religious`\_parameter is typically very useful to identify religious holidays, which in some countries, can be specific to certain religious groups. Unless a\_`religious`\_holiday has either\_`national`\_or\_`local`\_attribute also set to\_`true`, it will very likely be an optional holiday for certain religious groups, or no holiday at all.\n\n## Religion codes\n\n| Code | Religion |\n| --- | --- |\n| 1 | Christianity |\n| 2 | Islam |\n| 3 | Buddhism |\n| 4 | Confucianism |\n| 5 | Hinduism |\n| 6 | Jainism |\n| 7 | Judaism |\n| 8 | Sikhism |\n| 9 | Yazidism |\n| 10 | Zoroastrianism |\n| 11 | Baha-i Faith |" tags: - '' parameters: - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: $ref: >- #/components/schemas/V1HolidaysGetResponsesContentApplicationJsonSchemaItems '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/GetV1HolidaysRequestUnauthorizedError' servers: - url: https://api.holidays.rest components: schemas: V1HolidaysGetResponsesContentApplicationJsonSchemaItemsName: type: object properties: de: type: string en: type: string tr: type: string required: - de - en - tr title: V1HolidaysGetResponsesContentApplicationJsonSchemaItemsName V1HolidaysGetResponsesContentApplicationJsonSchemaItemsDay: type: object properties: actual: type: string observed: type: string required: - actual - observed title: V1HolidaysGetResponsesContentApplicationJsonSchemaItemsDay V1HolidaysGetResponsesContentApplicationJsonSchemaItems: type: object properties: country_code: type: string country_name: type: string date: type: string format: date name: $ref: >- #/components/schemas/V1HolidaysGetResponsesContentApplicationJsonSchemaItemsName isNational: type: boolean isReligious: type: boolean isLocal: type: boolean isEstimate: type: boolean day: $ref: >- #/components/schemas/V1HolidaysGetResponsesContentApplicationJsonSchemaItemsDay religion: type: string regions: type: array items: description: Any type required: - country_code - country_name - date - name - isNational - isReligious - isLocal - isEstimate - day - religion - regions title: V1HolidaysGetResponsesContentApplicationJsonSchemaItems GetV1HolidaysRequestUnauthorizedError: type: object properties: error: type: string required: - error title: GetV1HolidaysRequestUnauthorizedError securitySchemes: bearerAuth: type: http scheme: bearer ``` ## SDK Code Examples ```python holidays_example import requests url = "https://api.holidays.rest/v1/holidays" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript holidays_example const url = 'https://api.holidays.rest/v1/holidays'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go holidays_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.holidays.rest/v1/holidays" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby holidays_example require 'uri' require 'net/http' url = URI("https://api.holidays.rest/v1/holidays") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java holidays_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.holidays.rest/v1/holidays") .header("Authorization", "Bearer ") .asString(); ``` ```php holidays_example request('GET', 'https://api.holidays.rest/v1/holidays', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp holidays_example using RestSharp; var client = new RestClient("https://api.holidays.rest/v1/holidays"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift holidays_example import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.holidays.rest/v1/holidays")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```