Choliday API

Swiss holiday REST API · v1

← App

Base URL: https://choliday.rappo.dev/api · Rate limit: 300 req/min · Format: JSON (default) or CSV

Endpoints

GET /holidays/{country}/{region}[/{year}]

Returns all holidays for a country/region. Year defaults to the current year.

Path parameters

Param	Example	Description
country	`CH`	ISO 3166-1 alpha-2 country code
region	`ZH` or `ZH,BE`	Canton code. Comma-separated for multi-region union.
year	`2025`	Optional. 1900–2200. Defaults to current year.

Query parameters

Param	Values	Description
format	`csv`	Returns CSV instead of JSON
fields	`date,name_de`	Comma-separated field subset
nonwork	`1`	Only return non-workday holidays
weekday	`1,5`	Only holidays on these weekdays (0=Sun … 6=Sat)

Example

GET /api/holidays/CH/ZH/2025

{
  "country": "CH",
  "region": "ZH",
  "year": 2025,
  "count": 13,
  "holidays": [
    {
      "date": "2025-01-01",
      "name_de": "Neujahr",
      "name_fr": "Nouvel An",
      "name_it": "Capodanno",
      "is_always_nonworkday": true
    },
    ...
  ]
}

GET /holidays/{country}/{region}/next

Returns the next upcoming holiday from today.

Example

GET /api/holidays/CH/BE/next

{
  "country": "CH",
  "region": "BE",
  "holiday": { "date": "2025-05-29", "name_de": "Auffahrt", ... }
}

GET /holidays/{country}/{region}/{date}

Checks whether a specific date is a holiday. Date format: YYYY-MM-DD.

Example

GET /api/holidays/CH/ZH/2025-08-01

{
  "country": "CH",
  "region": "ZH",
  "date": "2025-08-01",
  "is_holiday": true,
  "holiday": { "date": "2025-08-01", "name_de": "Nationalfeiertag", ... }
}

GET /holidays/{country}/heatmap/{year}

Returns holiday counts for every region in the country. Used to render the map heatmap.

Example

GET /api/holidays/CH/heatmap/2025

{ "AG": 15, "AI": 14, "AR": 11, "BE": 12, ... }

GET /countries

Lists all supported countries.

GET /countries/{country}/regions

Lists all regions (cantons) for a country.

Holiday object fields

Field	Type	Description
date	string	ISO date `YYYY-MM-DD`
name_de	string	German name
name_fr	string	French name
name_it	string	Italian name
is_always_nonworkday	boolean	True if officially non-working across all employers

Caching

All responses include Cache-Control: public, max-age=86400, stale-while-revalidate=604800.

Machine-readable spec

openapi.json — OpenAPI 3.1 spec, compatible with Swagger UI, Insomnia, Postman, and similar tools.

Choliday is open source. Holiday data is algorithmically generated per Swiss law.