Документация API

Аутентификация

Каждый запрос должен содержать действующий ключ API. Ключ можно передать тремя способами:

Заголовок X-API-Key (рекомендуется)

GET /api/v1/name-days?date=2026-03-19 HTTP/1.1
Host: calendar.lt
X-API-Key: clt_your_api_key_here

Заголовок Authorization: Bearer

Authorization: Bearer clt_your_api_key_here

Параметр запроса (только для тестирования)

GET /api/v1/name-days?date=2026-03-19&api_key=clt_your_api_key_here

Рекомендуем использовать заголовок X-API-Key. Никогда не раскрывайте ключ публично.

Конечные точки

GET /api/v1/laisvadienis Публичный

Публичный эндпоинт — ключ API не требуется. Возвращает true, если указанная дата является нерабочим днём в Литве (воскресенье или государственный праздник), иначе false.

Также возвращает поле shorter_workday — согласно ст. 113 Трудового кодекса Литвы рабочий день непосредственно перед государственным праздником сокращается на один час. Это применяется даже если праздник выпадает на субботу.

Лимит: 60 запросов в минуту и 10 000 запросов в месяц, отслеживается по IP-адресу.

Параметры

Параметр	Тип	Обязательный	Описание
`date`	string	Да	Дата в формате YYYY-MM-DD

Поля ответа

Параметр	Тип	Описание
`date`	string	Date in YYYY-MM-DD format
`laisvadienis`	boolean	`true` if non-working day (weekend or red holiday)
`reason`	string\|null	`"saturday"`, `"sunday"`, `"public_holiday"`, or `null`
`holiday_name`	string\|null	Lithuanian holiday name when reason is `"public_holiday"`, otherwise `null`
`shorter_workday`	boolean	`true`, если это рабочий день (`laisvadienis: false`) и следующий календарный день является красным государственным праздником — рабочий день сокращается на 1 ч. согласно ст. 113 ТК. Всегда `false` в нерабочие дни.

Пример запроса

curl "https://calendar.lt/api/v1/laisvadienis?date=2026-06-23"

Пример ответа

// Tuesday before Rasos ir Joninių diena (Jun 24) — workday is shortened:
{
  "date": "2026-06-23",
  "laisvadienis": false,
  "reason": null,
  "holiday_name": null,
  "shorter_workday": true
}

// The red holiday itself:
{
  "date": "2026-06-24",
  "laisvadienis": true,
  "reason": "public_holiday",
  "holiday_name": "Rasos ir Joninių diena",
  "shorter_workday": false
}

// Regular working day:
{
  "date": "2026-06-22",
  "laisvadienis": false,
  "reason": null,
  "holiday_name": null,
  "shorter_workday": false
}

// Saturday (holiday falls on Saturday — Friday would be shorter_workday: true):
{
  "date": "2026-01-03",
  "laisvadienis": true,
  "reason": "saturday",
  "holiday_name": null,
  "shorter_workday": false
}

GET /api/v1/days Публичный

Returns laisvadienis and shorter_workday status for every day in a date range — a batch version of /api/v1/laisvadienis. No API key required.

Rate limits (IP-based): 20 requests/min · 2 000 requests/month. Maximum range: 366 days per request.

Параметры

Параметр	Тип	Обязательный	Описание
`from`	string	Да	Start date in YYYY-MM-DD format (inclusive)
`to`	string	Да	End date in YYYY-MM-DD format (inclusive). Must not be earlier than `from`.

Поля ответа

Параметр	Тип	Описание
`from`	string	Echoes the `from` parameter
`to`	string	Echoes the `to` parameter
`count`	integer	Number of days in the response
`days[].date`	string	Date in YYYY-MM-DD format
`days[].laisvadienis`	boolean	`true` if non-working day (weekend or red public holiday)
`days[].holiday_name`	string\|null	Lithuanian name of the red public holiday, or `null`
`days[].shorter_workday`	boolean	`true`, если это рабочий день (`laisvadienis: false`) и следующий календарный день является красным государственным праздником — рабочий день сокращается на 1 ч. согласно ст. 113 ТК. Всегда `false` в нерабочие дни.

Пример запроса

curl "https://calendar.lt/api/v1/days?from=2026-05-01&to=2026-05-31"

Пример ответа

{
  "from": "2026-05-01",
  "to": "2026-05-31",
  "count": 31,
  "days": [
    {
      "date": "2026-05-01",
      "laisvadienis": true,
      "holiday_name": "Tarptautinė darbo diena",
      "shorter_workday": false
    },
    {
      "date": "2026-05-02",
      "laisvadienis": false,
      "holiday_name": null,
      "shorter_workday": false
    },
    {
      "date": "2026-05-03",
      "laisvadienis": true,
      "holiday_name": "Motinos diena",
      "shorter_workday": false
    },
    {
      "date": "2026-05-04",
      "laisvadienis": false,
      "holiday_name": null,
      "shorter_workday": false
    }
  ]
}

Error responses

HTTP	Код ошибки	Описание
400	`missing_param`	Both `from` and `to` are required
400	`invalid_date`	Either date is not a valid YYYY-MM-DD value
400	`invalid_range`	`from` is later than `to`
400	`range_too_large`	Range exceeds 366 days — split into smaller requests
429	`rate_limit_minute`	20 requests/minute exceeded
429	`rate_limit_month`	2 000 requests/month exceeded

GET /api/v1/holidays

Возвращает литовские праздники для указанной даты или года.

Параметры

Параметр	Тип	Обязательный	Описание
`date`	string	Да*	Дата в формате YYYY-MM-DD — returns holidays for that specific date
`year`	integer	Да*	Year (1583–2100) — returns all holidays for the entire year
`lang`	string	Нет	Язык: lt, en, pl, ru (по умолчанию: lt)

Provide either date or year — not both.

Поля ответа

Параметр	Тип	Описание
`date` / `year`	string / integer	Echoes the query parameter
`count`	integer	Number of holidays returned
`holidays[].date`	string	Date in YYYY-MM-DD
`holidays[].name`	string	Name in requested language
`holidays[].name_lt/en/pl/ru`	string	Names in all four languages
`holidays[].type`	string	`public`, `traditional`, `religious`, `school`, `other`
`holidays[].is_red`	boolean	`true` if this is a non-working day (laisvadienis) per DK 123 str.

Пример запроса

// By date:
curl "https://calendar.lt/api/v1/holidays?date=2026-04-05&lang=en" \
  -H "X-API-Key: clt_your_api_key_here"

// Full year:
curl "https://calendar.lt/api/v1/holidays?year=2026&lang=lt" \
  -H "X-API-Key: clt_your_api_key_here"

Пример ответа

{
  "date": "2026-04-05",
  "count": 1,
  "holidays": [
    {
      "date": "2026-04-05",
      "name": "Easter Sunday",
      "name_lt": "Šv. Velykos",
      "name_en": "Easter Sunday",
      "name_pl": "Niedziela Wielkanocna",
      "name_ru": "Пасха",
      "type": "public",
      "is_red": true
    }
  ]
}

GET /api/v1/name-days

Возвращает именины, отмечаемые в указанный день.

Параметры

Параметр	Тип	Обязательный	Описание
`date`	string	Да	Дата в формате YYYY-MM-DD
`lang`	string	Нет	Язык: lt, en, pl, ru (по умолчанию: lt)

Пример запроса

curl "https://calendar.lt/api/v1/name-days?date=2026-03-19&lang=lt" \
  -H "X-API-Key: clt_your_api_key_here"

Пример ответа

{
  "date": "2026-03-19",
  "lang": "lt",
  "count": 3,
  "name_days": [
    { "name": "Juozapas", "gender": "m" },
    { "name": "Juozas",   "gender": "m" },
    { "name": "Juzė",     "gender": "f" }
  ]
}

GET /api/v1/day

Возвращает полные данные дня: праздники и именины.

Параметры

Параметр	Тип	Обязательный	Описание
`date`	string	Да	Дата в формате YYYY-MM-DD
`lang`	string	Нет	Язык: lt, en, pl, ru (по умолчанию: lt)

Поля ответа

Параметр	Тип	Описание
`date`	string	Date in YYYY-MM-DD
`lang`	string	Language used for names
`day_of_week`	integer	0 = Sunday, 1 = Monday … 6 = Saturday
`is_weekend`	boolean	`true` for Saturday or Sunday
`week_number`	integer	ISO 8601 week number
`holidays[].name`	string	Holiday name in requested language
`holidays[].name_lt/en`	string	Names in Lithuanian and English
`holidays[].date`	string	Holiday date (YYYY-MM-DD)
`holidays[].type`	string	Holiday category
`holidays[].is_red`	boolean	`true` if non-working day (laisvadienis)
`name_days[].name`	string	Name-day name
`name_days[].gender`	string	`"m"` or `"f"`

Пример запроса

curl "https://calendar.lt/api/v1/day?date=2026-05-03&lang=en" \
  -H "X-API-Key: clt_your_api_key_here"

Пример ответа

{
  "date": "2026-05-03",
  "lang": "en",
  "day_of_week": 0,
  "is_weekend": true,
  "week_number": 18,
  "holidays": [
    {
      "name": "Mother's Day",
      "name_lt": "Motinos diena",
      "name_en": "Mother's Day",
      "date": "2026-05-03",
      "type": "traditional",
      "is_red": true
    }
  ],
  "name_days": [
    { "name": "Irma", "gender": "f" }
  ]
}

The `is_red` flag

The is_red field marks a holiday as a non-working day (laisvadienis) per the Lithuanian Labour Code (DK 123 str.). It is managed entirely in the database — no hardcoded lists in the application code.

The following holidays carry is_red: true:

Holiday	Date	Computed
Naujųjų metų diena	Jan 1
Lietuvos valstybės atkūrimo diena	Feb 16
Lietuvos nepriklausomybės atkūrimo diena	Mar 11
Šv. Velykos (Easter Sunday)	Variable	Yes
Antroji Velykų diena (Easter Monday)	Variable	Yes
Tarptautinė darbo diena	May 1
Motinos diena (Mother's Day)	1st Sunday of May	Yes
Rasos ir Joninių diena	Jun 24
Valstybės (Mindaugo karūnavimo) diena	Jul 6
Žolinė	Aug 15
Visų Šventųjų diena	Nov 1
Mirusiųjų atminimo (Vėlinių) diena	Nov 2
Kūčių diena	Dec 24
Šventosios Kalėdos (pirma diena)	Dec 25
Šventosios Kalėdos (antra diena)	Dec 26
Tėvo diena (Father's Day)	1st Sunday of June	Yes

Note: type reflects the holiday's cultural category (public, traditional, religious, etc.) and is independent of is_red. For example, Motinos diena has type: "traditional" but is_red: true. Always use is_red (not type) to determine whether a day is non-working.

Флаг `shorter_workday`

Трудовой кодекс Литвы (ст. 113) требует, чтобы рабочий день непосредственно перед государственным праздником (šventinių dienų išvakarės) был сокращён на один час. Применяется ко всем работникам независимо от режима рабочего времени.

Правило применяется к календарному дню непосредственно перед праздником — не к последнему рабочему дню недели. Возможные случаи:

Праздник выпадает на	Сокращённый рабочий день
Вторник → понедельник сокращён
Среду → вторник сокращён
Субботу → пятница сокращена
Воскресенье → суббота уже выходной, ни один день не сокращается
Понедельник → воскресенье уже выходной, ни один день не сокращается

Важно: shorter_workday всегда false, когда laisvadienis: true. Нерабочий день не может одновременно быть сокращённым рабочим днём.

Практическое применение

Используйте этот флаг для автоматизации кадровых и расчётных систем — без необходимости вести собственный календарь сокращённых дней. Запросите любую дату и реагируйте на shorter_workday: true:

const res = await fetch("https://calendar.lt/api/v1/laisvadienis?date=2026-06-23");
const { laisvadienis, shorter_workday } = await res.json();

if (laisvadienis)      return "Day off";
if (shorter_workday)   return "Work until 16:00 today (1 hour shorter)";
                       return "Normal working day";

Коды ошибок

HTTP	Код ошибки	Описание
401	`missing_key`	Ключ API не указан.
401	`invalid_key`	Ключ API недействителен или неактивен.
401	`expired_key`	Срок действия ключа API истёк.
429	`rate_limit_minute`	Превышен лимит запросов в минуту.
429	`rate_limit_day`	Превышен дневной лимит запросов.
400	`invalid_date`	Неверный формат даты. Используйте YYYY-MM-DD.
400	`missing_param`	Отсутствует обязательный параметр.
400	`invalid_year`	Year is outside the supported range (1583–2100)

Ограничение частоты запросов

Каждый ключ API имеет два скользящих ограничения: по количеству запросов в минуту и в сутки. При превышении лимита ответ 429 укажет, какой лимит достигнут.

Endpoint	Auth required	Rate limit
`/api/v1/laisvadienis`	No	60 req/min · 10 000 req/month (IP-based)
`/api/v1/holidays`	Yes	Per API key plan
`/api/v1/name-days`	Yes	Per API key plan
`/api/v1/day`	Yes	Per API key plan

Получить доступ к API

Для получения ключа API свяжитесь с нами по электронной почте.

Связаться

Документация API

Аутентификация

Заголовок X-API-Key (рекомендуется)

Заголовок Authorization: Bearer

Параметр запроса (только для тестирования)

Конечные точки

Параметры

Поля ответа

Пример запроса

Пример ответа

Параметры

Поля ответа

Пример запроса

Пример ответа

Error responses

Параметры

Поля ответа

Пример запроса

Пример ответа

Параметры

Пример запроса

Пример ответа

Параметры

Поля ответа

Пример запроса

Пример ответа

The is_red flag

Флаг shorter_workday

Практическое применение

Коды ошибок

Ограничение частоты запросов

Получить доступ к API

The `is_red` flag

Флаг `shorter_workday`