Reference
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
country |
string | yes | Two-letter ISO 3166-1 code, for example UA or DE. |
year |
int | no | 1976 to 2075. Default: current UTC year. |
type |
string | no | Public, Bank, School, Authorities, Optional or Observance. Default: all. |
Example request
curl -s "https://api2.globus.studio/v2/holidays?country=DE&year=2026"
A holidays API answers a calendar question with JSON: which dates does a country treat as public holidays in a given year, and what are they called. The response carries the English name, the local name, the holiday type and the next upcoming date, so one request covers the schedule behind a support rota or an email plan.
curl -s "https://api2.globus.studio/v2/holidays?country=DE&year=2026"The endpoint accepts GET, POST and PUT. Parameters work in the query string or in a JSON body, so a server-side client can send a filter without building a URL.
What the response contains
country repeats the code you sent, country_name spells it out, and year repeats the year. total counts the rows, holidays holds the calendar, and next points at the first date that has not passed yet.
Each holiday has date in Y-m-d, name in English, local_name in the country’s language, and types with one or more categories. global is true when the date applies nationwide. counties lists regional codes when it does not. fixed marks a holiday that keeps the same calendar date every year. launch_year is set when a holiday starts applying only from a certain year.
Dates are sorted ascending, so the first row is the earliest holiday of the year.
Country and year
country is a two-letter ISO 3166-1 code. Case does not matter: de and DE return the same calendar.
year defaults to the current UTC year. The feed covers 1976 to 2075. A country may have a shorter range, and a request outside it returns unsupported_year instead of an empty list. An unknown code returns unknown_country.
Types and regional dates
Six types are available: Public, Bank, School, Authorities, Optional and Observance. The type parameter filters the list and is case-insensitive. A filter that matches nothing returns total: 0 with an empty array, which is a valid answer rather than an error.
Most requests want Public. The other types matter for payroll, school planning and office closures, where a bank holiday is not always a day off for everyone. A holiday with a counties list applies only to those regions, so a national count can overstate the days a specific office is closed.
Local names come back as UTF-8. Cyrillic, Greek and accented Latin names are not escaped, which keeps a dropdown readable without a second decoding step.
Caching and failure behaviour
A successful calendar is cached for a day. The last good answer is kept for a month: if the feed fails, the endpoint returns that snapshot with meta.stale: true and the X-GS-Stale: 1 header instead of an error. A client that shows dates can keep working through a short outage, and a client that must be exact can check the flag and retry later.
The endpoint sits in the network tier at 30 requests per minute. A 429 carries Retry-After in seconds.
Related
The full parameter table, every error code and a live request are on the holidays API documentation page.
A longer walkthrough with planning examples: Public holidays calendar: 5 uses that hold up.
Country codes come from ISO 3166-1.