Поиск документов в базе ГАРАНТ по реквизитам или контексту.

query — 3–5 КЛЮЧЕВЫХ СЛОВ, а не фраза-тезис. Гарант трактует запрос как конъюнкцию всех слов: длинная формулировка даёт одно-два случайных попадания или ноль. «продление домашнего ареста мотивированность» — рабочий запрос; «суд обязан привести конкретные фактические обстоятельства» — нет. Возвращает {total, страница, всего_страниц, items[...], kinds[]}, где kinds — распределение находок по видам (акты власти, высшие суды, комментарии). doc_id использовать дальше в garant_document / garant_article / garant_revisions.

Перечень находок кэшируется (тексты норм — никогда). Ответ из кэша несёт в provenance из_кэша, дата_записи, возраст_часов и срок_годности_часов: документ, появившийся в базе после записи, в таком ответе не появится. use_cache=False — потребовать свежего похода в «Гарант»; применять, когда важна именно сегодняшняя полнота выдачи.

Оглавление документа: разделы и статьи с идентификаторами элементов.

Полезно, когда garant_article не нашёл статью — посмотреть, как она названа в акте.

Полный текст документа по doc_id + provenance (редакция, дата актуальности, hash).

Использовать, когда нужен весь акт. Для одной статьи/пункта — garant_article (дешевле и точнее).

Полноту проверяют сравнением: страниц — сколько загружено, страниц_в_документе — сколько их всего (null, если «Гарант» числа не назвал). Расходятся — ответ несёт _предупреждение, и в нём названа причина: упёрлись в max_pages (повтор с бо́льшим значением помогает) или «Гарант» не отдал пакет страниц (не помогает, смотрите логи).

max_pages — сколько страниц загружать. Параметр выставлен наружу потому, что на длинном акте ответ несёт _предупреждение с советом увеличить max_pages: совет, которому нельзя последовать, хуже отсутствия совета. Не указан — берётся умолчание клиента; второго его написания здесь нет намеренно, оно разошлось бы с первым молча.

_нормализация — присутствует ВСЕГДА, как и у garant_article: текст получен нормализацией HTML страницы «Гаранта», а не выгрузкой оригинала, и редакционные врезки могли попасть в него неотмеченными. Обещание «полный текст» относится к охвату страниц, а не к дословности разметки. Что именно нормализация ставит в тексте и что в нём меняет, перечислено в самом ключе _нормализация каждого ответа; второго его написания здесь нет намеренно: оно разошлось бы с первым молча — и разошлось бы там, где читатель переносит цитату в подаваемый документ.

Дословный текст конкретной статьи или пункта.

article — номер статьи или пункта: "97", "109", "5". Собирается цепочкой: оглавление → определение страницы → текст страниц → вырезка от заголовка статьи до следующего (отдельного эндпоинта «статья» у Гаранта нет).

Основной инструмент сверки цитат перед подачей документа; обрывать цитату на середине запрещено. Два ключа ответа читать обязательно: _предупреждение — конец фрагмента не подтверждён, и риск бывает ДВУХ родов: текст неполный (конец не поместился в загруженные страницы) либо ИЗБЫТОЧНЫЙ — в вырезку попал чужой текст, начало соседней статьи. Какой именно риск остался, сказано в самом предупреждении; избыточность опаснее тем, что цитата выглядит целой; _нормализация — присутствует ВСЕГДА: текст получен нормализацией HTML страницы «Гаранта», и редакционные врезки («Статья … дополнена … с … г.») могли попасть в вырезку неотмеченными. Сверяйте с окном подписки. Дословного сличения с оригиналом инструмент не обещает и обещать не может: оригинал в машинном виде ему не отдают, есть только нормализованный HTML. Что именно нормализация ставит в тексте и что в нём меняет, перечислено в самом ключе _нормализация каждого ответа; второго его написания здесь нет намеренно: оно разошлось бы с первым молча — и разошлось бы там, где читатель переносит цитату в подаваемый документ.

Список редакций документа и изменяющих актов. Кэш не используется.

Для каждой редакции: статус (действующая / утратила силу), период действия, изменяющий акт, id_редакции. Периодов бывает больше одного — тогда все они перечислены в ключе периоды, а действует_с/действует_по называют лишь первый из них. Смежность периодов СЧИТАЕТСЯ по датам: разбиение непрерывного срока на записи перерывом не называется. Но держится она не всегда на одной арифметике: период, начинающийся на следующий день после конца предыдущего, смежен лишь потому, что границу МЫ читаем включительно, а как её трактует сам «Гарант», на живой базе НЕ проверено. Там, где запись называет периоды смежными, на чём эта смежность стоит, сказано в её ключе _предупреждение. Там, где посчитан разрыв, запись об этом молчит: непрерывность там не утверждается вовсе, а действует_с ошибается в сторону поздней даты. ЧЕМ вызван посчитанный разрыв, мы не знаем: карта эндпоинтов этого не объясняет. Наше прочтение — ЕСЛИ акт приостанавливали и возвращали в силу — на живой базе НЕ проверено, и выводить из перерыва между периодами, что норма не действовала, инструмент оснований не даёт. периоды равно null означает, что карта эндпоинтов их не описывает. Сказанное едет не только здесь, но и ключом _предупреждение у самой записи, и ветвей у ключа больше, чем названо выше: там же говорится, например, когда сама дата в действует_с не разобралась как дата. Перечислить их здесь не устаревая описание не может — полон только сам ключ, и читать надо его: описание инструмента остаётся у инструмента, а запись уходит дальше — в пересказ, в черновик, в следующий шаг.

Основа мониторинга: если действующая редакция новее той, в которой норма была процитирована раньше, цитату надо пересверить — сама по себе она не устаревает заметно.

КАКАЯ редакция действовала на дату. Текста нормы НЕ возвращает.

on_date — «ДД.ММ.ГГГГ». Ответ — запись о редакции: её название, статус, период действия, изменяющий акт и id_редакции. Ни текста статьи, ни блока provenance в нём нет.

действует_с и действует_по в ответе — границы ТОГО периода, которым покрыта запрошенная дата (периодов у редакции бывает несколько; чем это вызвано, карта эндпоинтов не объясняет); он же отдельным ключом _период_на_дату. Полный перечень периодов — в ключе периоды и в garant_revisions.

В день СТЫКА редакций под дату подходят обе: границу периода МЫ читаем включительно с обеих сторон, а как её трактует сам «Гарант», не проверено. Тогда в ответе стоит ключ _предупреждение: он называет всех кандидатов и говорит, что отданная выбрана порядком списка, а не доказана. Тот же ключ появляется, среди прочего, когда карта эндпоинтов не описывает список периодов, когда периодов у записи больше одного и когда сама дата в действует_с не разобралась как дата. Перечень здесь неполный намеренно: ветвей у ключа больше, чем описание способно перечислить не устаревая, — полон только сам ключ, и читать надо его.

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

ЧЕМ ВЗЯТЬ ТЕКСТ ТОЙ РЕДАКЦИИ. Прямого способа нет: garant_article и garant_document параметра редакции не принимают и собирают provenance по ДЕЙСТВУЮЩЕЙ редакции. Поэтому текст, взятый ими, относится к сегодняшнему дню, даже если этот инструмент вернул другую редакцию, — и ставить их рядом как цитату на прошлую дату нельзя.

Есть непроверенная возможность: id_редакции — это documentId самой редакции, и он МОЖЕТ приниматься как doc_id в garant_article. Проверить это без живой подписки невозможно, поэтому до проверки считать, что способа нет, и говорить пользователю прямо: редакция установлена, дословный текст в ней — нет.

Дерево видов информации ГАРАНТа: «Акты органов власти», «Высшие суды» и т.д.

Нужно, чтобы узнать ТОЧНОЕ название вида для garant_practice(kind=...). node_id=0 — верхний уровень (21 узел); подставьте id узла, чтобы раскрыть ветку.

Частый случай: выяснить, в каком виде лежат акты кассационных судов общей юрисдикции — в выдаче «Высшие суды» их нет, там только КС РФ и ВС РФ.

Поиск судебной практики: КС РФ, ВС РФ, кассационные суды.

Вид информации и период применяются НА СЕРВЕРЕ Гаранта: /list/kind → /list/filter → /list/page. Уточнение по суду (court) — ЕДИНСТВЕННОЕ исключение: серверного фильтра по суду в этой цепочке нет, поэтому оно делается отбором по подстроке заголовка на клиенте, уже внутри отфильтрованного сервером вида. Значит, выдача по court заведомо неполна: акт нужного суда, чей заголовок назван иначе, в неё не попадёт.

Акты кассационных судов общей юрисдикции в подписке недоступны: вид «Судебная практика» пуст (0 документов), тексты КСОЮ лежат в отдельной базе d.garant.ru, к которой доступа нет. Искать их здесь бессмысленно — рабочий канал один: вид «Высшие суды» (КС РФ и ВС РФ).

kind — вид информации; по умолчанию «Высшие суды» (КС РФ и ВС РФ). Полный перечень видов — garant_kinds. court — уточнение внутри выбранного вида; отбор по заголовку на клиенте (см. исключение выше), а не серверный фильтр. date_from / date_to — "ДД.ММ.ГГГГ".

ВЫДАЧА ЗАВЕДОМО НЕПОЛНАЯ, и ответ говорит об этом ключом _предупреждение: берётся только первая страница отфильтрованного списка, список режется по limit, а court отбирается по заголовку на клиенте. Вывод «у этого суда практики нет» из такого ответа не следует.

Поле номер_в_заголовке — то, что стоит после «№» в заголовке. Номером ДЕЛА оно является не всегда: там же стоят номера постановлений Пленума и обзоров практики. Прежнее поле статуса с «✓» удалено: оно называло подтверждённым то, что никто не подтверждал. Приоритет источников практики: КС РФ и ВС РФ выше кассационных судов общей юрисдикции.