Public holidays calendar: 5 uses that hold up

Public holidays calendar

A public holidays calendar is one of those datasets that looks trivial until a schedule depends on it. The date is public, the name is public, and yet teams rebuild the same list by hand every year, then discover in December that a moveable feast landed on a different week.

The holidays API returns the calendar of one country for one year as JSON. Dates, English names, local names, holiday types and a next block come back in one response. It needs no key or account, and nothing is scraped.

What a public holidays calendar returns

The payload has a flat shape. country and country_name identify the place, year identifies the period, and holidays is the sorted list. Each row carries date, name, local_name, types, global, counties, fixed and launch_year.

curl -s "https://api2.globus.studio/v2/holidays?country=UA&year=2026"

The next object is the part a dashboard uses most: the first holiday that has not passed, with days_left counted from the current UTC day. A widget can show it without sorting the list again.

Five uses that hold up

A support rota needs to know when staff in one country are off and customers in another are still working. Pull the calendar for each country once, store the dates, and let the rota tool mark the days. The API supplies the dates; the rota tool decides how to use them.

A launch on a national holiday gets less attention and fewer people to fix a problem. Check the target country before fixing the date. The same check catches the week between Christmas and New Year, when a release may be technically possible and practically unstaffed.

Payment runs and payroll cutoffs move around bank holidays. A finance script that assumes the last working day is always the 30th will miss a month sooner or later. The Bank type is the one to read here.

School holidays and optional observances matter for local teams even when the office stays open. A calendar with types lets one dataset answer both questions without a second source.

A support reply that promises an answer "tomorrow" reads badly when tomorrow is a public holiday in the customer’s country. The local name is useful in that reply, because the customer recognizes it immediately.

Each use keeps a person in charge of the decision. A calendar tells you which day is a holiday. It does not tell you whether the business closes, whether the deadline moves, or whether the customer celebrates it.

Types matter more than the count

The response separates Public, Bank, School, Authorities, Optional and Observance. A country can list more entries than the days most offices are closed. Counting every row gives a number that looks precise and answers nothing.

Filter with type=Public for a general view. Use type=Bank when money moves, and type=School when the audience is families. A filter that matches nothing returns an empty list with total: 0, which is a valid answer.

Regional dates and local names

Some holidays apply only to part of a country. global: false and a counties list show that. A national office policy built on the national list can close a branch on a day when the region does not observe the holiday, or keep it open on a day when it does.

local_name is the holiday in the country’s own language. Keeping it next to the English name avoids the awkward translation of a cultural date and helps when the calendar is shown to local staff.

Cache, snapshots and the stale flag

A successful answer is cached for a day, because a country calendar does not change between requests. The last good response is kept for a month. If the upstream feed fails, the endpoint returns that snapshot with meta.stale: true and X-GS-Stale: 1.

A date picker should not break because a public feed is down for two minutes. A billing system should notice the flag and retry before it moves a payment run. The endpoint allows 30 requests per minute and returns 429 with Retry-After when a client exceeds it.

Put the calendar in code

A server-side job can fetch once a year per country and store the result:

curl -s "https://api2.globus.studio/v2/holidays?country=DE&year=2026&type=Public"

Store the date, the name and the types, then let each system decide what a holiday means for its own schedule. The API stays the same when a country adds a date; only the stored calendar needs a refresh.