OpenHolidays API

https://www.openholidaysapi.org/en/
Admin
OpenHolidays API is an open data project that provides public holiday and school holiday data across...
Tokens:21,948
Snippets:223
Trust Score:8.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example of errors field in Problem Details

Source: https://www.openholidaysapi.org/en/errors?q=

Example of the optional 'errors' extension member in the Problem Details object, showing a validation error for the 'validTo' field.

```json
{
    "validTo": [
      "The validTo field is required."
    ]
}
```

--------------------------------

### Query School Holidays in JSON format

Source: https://www.openholidaysapi.org/en?q=

Example query for school holidays in Austria (Carinthia) for 2022 with English output, formatted as JSON.

```powershell
curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json
```

```bash
curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/json' | json_pp
```

--------------------------------

### Query School Holidays in iCal format

Source: https://www.openholidaysapi.org/en?q=

Example query for school holidays in Austria (Carinthia) for 2022, returning data in iCal format.

```powershell
curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar'
```

```bash
curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar'
```

--------------------------------

### Example API call and error response

Source: https://www.openholidaysapi.org/en/errors?q=

Example API call that triggers a validation error and the resulting RFC 9457 Problem Details response. The request uses an invalid date range (greater than 3 years) and the response includes a 400 Bad Request status.

```http
https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2020-01-01&validTo=2023-12-31
```

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "pageSize": [
      "The field pageSize must be between 1 and 50."
    ]
  },
  "traceId": "00-0274bb16dcdf462bf27a7faedeacc79f-05c5cd5b5d411f8e-00"
}
```

--------------------------------

### GET /PublicHolidays

Source: https://www.openholidaysapi.org/en?q=

Queries public holidays for a country within a specified period. The example shows retrieving German public holidays for 2022 in iCal format.

```APIDOC
## [GET] /PublicHolidays

### Description
Queries public holidays for a country within a specified period. The example shows retrieving German public holidays for 2022 in iCal format.

### Method
GET

### Endpoint
https://openholidaysapi.org/PublicHolidays

### Parameters
#### Query Parameters
- **countryIsoCode** (string) - Required - ISO country code (e.g., DE)
- **validFrom** (date) - Required - Start date of the period (e.g., 2022-01-01)
- **validTo** (date) - Required - End date of the period (e.g., 2022-12-31)

### Request Example
```
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar' -o 'kalendar.ics'
```

### Response
#### Success Response (200)
Returns public holiday data in iCal format (or JSON if requested).

#### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### Query Swiss public holidays in iCal format with curl

Source: https://www.openholidaysapi.org/en

Queries the same Swiss public holidays as the JSON example, but requests the data in iCal format by setting the Accept header to 'text/calendar'.

```powershell
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/calendar'

```

```bash
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/calendar'

```

--------------------------------

### Get public holidays as iCal (Powershell 7)

Source: https://www.openholidaysapi.org/en?q=

Requests Swiss public holidays in iCal format by setting accept header to text/calendar.

```powershell
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/calendar'
```

--------------------------------

### Query groups for Belgium (BE) with curl (Bash)

Source: https://www.openholidaysapi.org/en?q=

Fetches the groups for school holidays in Belgium, using countryIsoCode=BE, and formats with json_pp.

```bash
curl -X GET 'https://openholidaysapi.org/groups?countryIsoCode=BE' -H 'accept: text/json' | json_pp
```

--------------------------------

### API call causing a validation error

Source: https://www.openholidaysapi.org/en/errors

An example API request that triggers a validation error due to parameter constraints.

```text
https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2020-01-01&validTo=2023-12-31
```

--------------------------------

### Query Swiss public holidays with curl (Bash)

Source: https://www.openholidaysapi.org/en?q=

Fetches public holidays for Switzerland from 2022-01-01 to 2022-06-30, with German output language, using json_pp.

```bash
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/json' | json_pp
```

--------------------------------

### Query groups for Belgium (BE) with curl (Powershell 7)

Source: https://www.openholidaysapi.org/en?q=

Fetches the groups (e.g., language boundaries) for school holidays in Belgium, using countryIsoCode=BE.

```powershell
curl -X GET 'https://openholidaysapi.org/groups?countryIsoCode=BE' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json
```

--------------------------------

### Query countries with curl (Bash)

Source: https://www.openholidaysapi.org/en?q=

Retrieves the list of countries supported by the OpenHolidays API using Bash, with json_pp for pretty-printing. Country codes follow ISO 3166-1.

```bash
curl -X GET 'https://openholidaysapi.org/Countries' -H 'accept: text/json' | json_pp
```

--------------------------------

### GET /SchoolHolidays

Source: https://www.openholidaysapi.org/en?q=

Queries school holidays for a country and optional subdivision within a date range. Supports JSON and iCal response formats.

```APIDOC
## [GET] /SchoolHolidays

### Description
Queries school holidays per country and administrative unit for a specified period (max three years). Optionally restricts holiday names to a specific language.

### Method
GET

### Endpoint
https://openholidaysapi.org/SchoolHolidays

### Parameters
#### Query Parameters
- **countryIsoCode** (string) - Required - ISO country code (e.g., AT)
- **subdivisionCode** (string) - Optional - Administrative subdivision code (e.g., AT-KÄ)
- **languageIsoCode** (string) - Optional - Language code for holiday names (e.g., EN)
- **validFrom** (date) - Required - Start date of the period (e.g., 2022-01-01)
- **validTo** (date) - Required - End date of the period (e.g., 2022-12-31)

### Request Example
```
curl -X GET 'https://openholidaysapi.org/SchoolHolidays?countryIsoCode=AT&subdivisionCode=AT-KÄ&languageIsoCode=EN&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/json'
```

### Response
#### Success Response (200)
Returns school holiday data in JSON format (or iCal format if requested with accept: text/calendar).

#### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### RFC 9457 error response example

Source: https://www.openholidaysapi.org/en/errors

The JSON response body returned by the API when a validation error occurs, following the RFC 9457 format.

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "pageSize": [
      "The field pageSize must be between 1 and 50."
    ]
  },
  "traceId": "00-0274bb16dcdf462bf27a7faedeacc79f-05c5cd5b5d411f8e-00"
}
```

--------------------------------

### Save Public Holidays to an iCal file

Source: https://www.openholidaysapi.org/en?q=

Saves German public holidays for 2022 to a file named 'kalendar.ics' using the -o parameter.

```powershell
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar' -o 'kalendar.ics'
```

```bash
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=DE&validFrom=2022-01-01&validTo=2022-12-31' -H 'accept: text/calendar' -o 'kalendar.ics'
```

--------------------------------

### Query Swiss public holidays (CH) with curl (Powershell 7)

Source: https://www.openholidaysapi.org/en?q=

Fetches public holidays for Switzerland (CH) from 2022-01-01 to 2022-06-30, with German (DE) output, using ConvertFrom-Json and ConvertTo-Json.

```powershell
curl -X GET 'https://openholidaysapi.org/PublicHolidays?countryIsoCode=CH&languageIsoCode=DE&validFrom=2022-01-01&validTo=2022-06-30' -H 'accept: text/json' | ConvertFrom-Json | ConvertTo-Json
```
Tokens:
Raw