oneapi
Sign in
Utile v1 / Sarbatori

Holidays of a year or range

A country's holidays for a year or an interval, with each one's type and the subdivisions it applies in, where they are not nationwide.

GET
https://oneapi.ro/api/utile/v1/sarbatori/{tara}

Path parameters

NameTypeDescriptionExample
tararequired string ISO 3166-1 alpha-2 country code (e.g. RO).

Query parameters

NameTypeDescriptionAccepted values
anoptional integer | null The calendar year, between 1970 and 2100. Defaults to the current year. Cannot be combined with de_la/pana_la. 1970 – 2100
de_laoptional string | null Optional, together with pana_la: the first day of the range, inclusive, YYYY-MM-DD. e.g. 2026-12-20
pana_laoptional string | null Optional, together with de_la: the last day of the range, inclusive. The range spans at most 3 calendar years. e.g. 2027-01-10
limbaoptional string | null Language of the names, such as ro, de or de_AT. Defaults to ro. It applies only to computed countries — for Romania the names come from the law, in Romanian. max 12 car.

How it behaves

  • A range across the turn of the year — "which holidays fall between 20 December and 10 January" — is requested with de_la and pana_la, in a single call; the response then carries de_la/pana_la instead of an. The period is given once: an together with a range returns 422.
  • A single day can carry TWO holidays. In 2026, in Romania, Whit Monday falls on Children's Day. That is why the response is a LIST, not a date→name map: a map would silently drop one of them.
  • For computed countries, tip comes from the library: official is generally a non-working day, while observance or season are marked days, not days off. The nelucratoare field reflects the declared type, NOT a check we performed against that country's legislation.
  • verificat is the most important field in the response. When it is false, the figures are good for planning but not for a legal deadline — for that you need the country's official source.
  • For Romania the route mirrors the legal calendar in the Financiar module (/financiar/v1/sarbatori?an=). These are not two datasets but the same one, exposed here as well so you need not switch modules when moving from Romania to the rest of the world.

What it is for

  • Build the leave calendar of a team spread across several countries.
  • Mark non-working days in a planner or a delivery calendar.
  • Compare how many days off one year has against another, for capacity planning.

Response structure

All fields below live inside data.

FieldTypeDescription
tara string The requested code, upper-cased.
an integer The requested year; absent when a range was requested.
inregistrari integer How many holidays are in the list.
zile[] array The holidays, in chronological order.
zile[].data string The day, YYYY-MM-DD.
zile[].nume string The name, in the requested language.
zile[].cheie string The stable identifier of the holiday (craciun_1, goodFriday) — compare on this, not on the name, which depends on the language.
zile[].mobila boolean Romania only: whether the date moves from year to year (Easter, Pentecost).
zile[].nelucratoare boolean Whether the day is off. For Romania this comes from the law; elsewhere from the declared type.
sursa string Where the days come from, stated explicitly.
verificat boolean true only if the source is the letter of the law.
temei string The legal act, where one exists.
observatie string A note on how to read the response: a computation convention or a limit of the data.
de_la string The first day of the requested range; only with de_la/pana_la.
pana_la string The last day of the requested range; only with de_la/pana_la.
zile[].tip string Computed countries only: the type declared by the library.

Response examples

GEThttps://oneapi.ro/api/utile/v1/sarbatori/RO
{
    "data": {
        "tara": "RO",
        "an": 2026,
        "inregistrari": 16,
        "zile": [
            {
                "data": "2026-01-01",
                "nume": "Anul Nou",
                "cheie": "anul_nou_1",
                "mobila": false,
                "nelucratoare": true
            }
        ],
        "sursa": "art. 139 din Codul Muncii (Legea 53/2003), prin modulul Financiar",
        "verificat": true,
        "temei": "Legea 53/2003, art. 139",
        "observatie": "Zilele vin din textul legii, prin modulul Financiar."
    }
}

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
404negasitThe country is not covered. The full list is at /utile/v1/sarbatori/tari.
422validareThe year or range falls outside 1970–2100, the range is incomplete, spans more than 3 calendar years or is combined with an.
429cota_depasitaThe plan's monthly quota has been exceeded (see Retry-After).

All errors share the same shape. eroare.cod is stable and is the value you should branch on in code — not the text in mesaj, which may change.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "The year or range falls outside 1970–2100, the range is incomplete, spans more than 3 calendar years or is combined with an.",
        "detalii": {
            "tara": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}