API

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

Базовый адрес — https://typikon.su/api/v2. Машинное описание: openapi.json. Начать знакомство удобно с /api/v2 — там счётчики корпуса и список ручек.

Лицензия

Корпус — под CC BY 4.0: берите свободно, в том числе для коммерческих целей, указывая источник.

Корпус «Уставные чтения» (typikon.su), CC BY 4.0

Оригиналы памятников — в общественном достоянии. Сканы, русские переводы и сведения о святых принадлежат их владельцам, см. условия использования.

Ключи и ограничения

Корпус свободен, а вот силы сервера — нет: один нетерпеливый скрипт в несколько потоков способен занять собой всё. Поэтому доступ отмерен, и чем лучше мы знаем клиента, тем больше ему полагается.

  • Без ключа — 60 запросов в час с адреса, кроме поиска. Этого хватает попробовать ручку и написать первый запрос.
  • С ключом — 30 запросов в минуту и 10 000 в сутки, все разделы, включая поиск. Ключ выпускается в профиле после входа на сайт; их может быть до пяти.
  • Нужно больше — напишите через обратную связь и расскажите, для чего: приложениям и постоянным потребителям ключи выдаются со своими числами.

Ключ передаётся заголовком Authorization: Bearer … (или X-Api-Key, если первый занят прокси). Он именной — не зашивайте его в страницу, которую отдаёте посетителям: всё, что попало в браузер, публично. Пропавший ключ отзывается в профиле, старый при этом сразу перестаёт работать.

curl -H "Authorization: Bearer tk_…" \
  "https://typikon.su/api/v2/search?q=пасха"

В каждом ответе видно, сколько осталось: X-RateLimit-Remaining и X-Quota-Remaining. Суточный счётчик обнуляется в полночь UTC (03:00 московского времени).

Чтения на день

Главное, ради чего стоит идти в этот API. Дата гражданская — всё остальное считается: подвижный круг с отступкой и преступкой, неподвижный календарь, памяти месяцеслова и зачала с текстом стихов.

GET /api/v2/calendar/{ГГГГ-ММ-ДД}

Что читается в этот день. Параметр lang=cs|ro — язык зачал.

GET /api/v2/calendar/today

Он же на сегодня.

GET /api/v2/days/{alias}

День по постоянному адресу — pascha, march-30, post-1-sb, — без пересчёта подвижного круга.

curl https://typikon.su/api/v2/calendar/2026-04-12

{
  "date": "2026-04-12",
  "churchDate": "2026-03-30",
  "movable": { "week": 1, "day": 0, "type": "Pascha" },
  "memories": { "primary": { "name": "..." }, "secondary": [] },
  "day": {
    "name": "Пасха",
    "readings": [
      { "slot": "song6", "title": "По шестой песни", "items": [ ... ] },
      { "slot": "gospelLiturgy", "title": "Евангелие на Литургии",
        "items": [ { "pericope": { "label": "Ин. 1", "verses": [ ... ] } } ] }
    ]
  }
}

Тексты и книги

GET /api/v2/texts

Список. Фильтры: book, readiness, saint, updatedSince. Тела текста здесь нет — оно в карточке.

GET /api/v2/texts/{alias|id}

Текст целиком. Для библейских книг — со стихами.

GET /api/v2/books

Книги корпуса.

GET /api/v2/books/{id}

Книга со списком своих текстов.

GET /api/v2/search?q=

Поиск по названию и содержимому. Ударения и церковнославянское написание набирать не нужно: «стражи» находит «стра́жи», «иоанна» — «і҆ѡа́нна». Фрагмент возвращается в исходном написании.

curl "https://typikon.su/api/v2/texts?readiness=ready&limit=2"

{
  "items": [ { "id": "...", "alias": "prolog-08-11-eupl", "name": "..." } ],
  "total": 2356,
  "limit": 2,
  "offset": 0
}

Справочники

GET /api/v2/pericopes

Зачала: источник, книга, номер, диапазоны стихов и дни, когда читается.

GET /api/v2/signs

Знаки Типикона по месяцеслову. Месяц и число — по старому стилю.

GET /api/v2/months

Месяцы, и /months/{alias} — с днями.

GET /api/v2/weeks

Седмицы Триоди, cycle=triodion|penticostarion.

GET /api/v2/saints/{id}

Тексты памяти святого и тексты, где он упоминается. Идентификатор — из святцев dneslov.org.

Соглашения

Списки приходят в одном виде: { items, total, limit, offset }. По умолчанию 50 записей, не больше 200 за раз.

Ошибка — всегда с телом: { "error": { "code": "not_found", "message": "..." } }. Коды: bad_request, not_found, unauthorized, forbidden, rate_limited, quota_exceeded, internal.

При исчерпании частоты или суточной квоты приходит 429 с заголовком Retry-After; с непризнанным или отозванным ключом — 401, а если ключ настоящий, но раздела не даёт — 403.

Запросы из браузера разрешены с любого источника. В каждом ответе есть заголовки X-License и Link: rel="license". Ответы по ключу помечены Cache-Control: private — общему кэшу их складывать незачем, остаток лимита у каждого свой.

Стабильность

В версии 2 поля только добавляются — существующие не переименовываются и не исчезают. Несовместимые изменения выйдут отдельной версией.

Версия 1 (/api/v1) осталась для мобильного приложения и выводится из обращения: её ответы помечены заголовками Deprecation, Sunset и Link: rel="successor-version". Новым клиентам следует брать вторую.

Вопросы и замечания — через обратную связь.