▣ HR · STANDARD DATA

Public Holidays API

Hosted on ApyHub

What it does

Public Holidays gives you a country-by-country holiday calendar for a given year. Send a country code, optionally add a year, and get back an array of holiday dates and names in the country’s primary language.

Use it when you need to block out non-working days in scheduling logic, calculate business-day deadlines, or pre-fill region-aware calendars in your product. The holiday list response includes date in YYYY-MM-DD format and name for each holiday, so you can display or store the results directly.

The service also lets you list the countries it supports. That makes it easy to build country selectors, validate user input before a holiday lookup, or sync supported markets into your internal configuration.

Public Holidays is a small reference-data API: simple inputs, predictable output, and no extra fields to parse. Keep your date logic aligned with local holiday schedules instead of hard-coding them.

▣ ENDPOINT 01 / 02

GET

List public holidays for a country and year

http://localhost:8080/apyhub/mono-go-public-holidays/holidays

QUICKSTARTGUIDE

Quickstart

Fetch public holidays for a country, optionally filtered by year.

curl -X GET "http://localhost:8080/apyhub/mono-go-public-holidays/holidays?country=DE&year=2025" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data array. Each item in the array is an object with date and name fields for a holiday.

{
  "data": [
    {
      "date": "2025-01-01",
      "name": "Neujahrstag"
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the public holidays for a specified country, optionally filtered by year.

Query Parameter(s)

Attribute	Type	Mandatory	Description
year	Integer	No	Year to list holidays for.
country	String	Yes	Country code.

Response

Returns a JSON object with a data array field. Each item in data is an object with date and name string fields representing a public holiday.

Parameter	Type	Mandatory	Description
data	Object Array	No	Array of public holiday objects.
data[].date	String	No	Holiday date in `YYYY-MM-DD` format.
data[].name	String	No	Holiday name in the country's primary language.

Query parameters

Name

Type

Description

yearOPTIONAL

integer

—

countryREQUIRED

string

—

▣ ENDPOINT 02 / 02

GET

List countries supported by the holidays endpoint

http://localhost:8080/apyhub/mono-go-public-holidays

QUICKSTARTGUIDE

Quickstart

Fetch the list of public holidays for the selected country.

curl -X GET "http://localhost:8080/apyhub/mono-go-public-holidays" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data array of strings, where each string is a public holiday entry.

{
  "data": ["New Year's Day", "Independence Day", "Christmas Day"]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a JSON object containing a data array of strings listing the countries supported by the holidays endpoint.

Response

Returns a JSON object with a data string array field. The array contains the supported country values.

Parameter	Type	Mandatory	Description
data	String Array	Yes	The list of supported countries returned by the endpoint.

Parameters

No parameters.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.