Согласуйте план сбора с контрактом получения данных

Оба заголовка API-ключа, фильтры дней UTC и итоги страниц. Сопоставьте план сбора с возможностями архива без обещаний полного охвата.

Получить API-ключ

Защищённое чтение и публичный статус

Защищённое чтение использует GET на https://api.redditcollector.com с X-API-Key: <ключ> либо Authorization: Bearer <ключ>. Оба формата передают ключ архива этого домена, не токен Reddit OAuth. Храните его на сервере, не в открытых файлах набора. Cookie Secure HttpOnly кабинета относится к отдельной сессии. Регистрация показывает ключ один раз сразу, до оплаты; пополнение не требуется для его выдачи.

/v1/search ищет публикации и комментарии. /v1/posts ограничивает выдачу публикациями, /v1/comments — комментариями. Все три принимают q, subreddit, author, kind, from, to, min_score, limit и page, но не id. kind принимает post и comment; для обоих типов через search не задавайте его. q — текстовый поиск без произвольного языка запросов, классификации тональности и собственной серверной аналитики.

/v1/item?id=... требует только id и ищет одну архивную запись, которая может отсутствовать. Родители и ответы автоматически не обходятся. /v1/subreddits принимает только prefix и limit для поиска названий сообществ, без постраничного обхода и гарантии глобально точных счётчиков. /v1/status публичен и бесплатен: статическое описание подтверждает ответ HTTP-приложения, не проверяя доступность поиска, свежесть записей, действительность ключа или баланс.

Временные границы и фактически доступные поля

from и to принимают YYYY-MM-DD в UTC и фильтруют created_utc, а не момент попадания записи в архив. Последний день to включается целиком. Это фильтры дней, а не значения курсора с точностью до времени суток. При делении работы по датам сохраняйте фактические границы и различайте время обработки задания и создания записи. Разбиение не доказывает полноты получения или расписания обновления архива.

min_score задаёт числовой порог оценки без сортировки, проверки экспертности или удаления спама. Внутренний порядок _doc не является хронологией, релевантностью, оценкой или случайным отбором. Более высокий порог меняет полученную группу, а не подтверждает качество. Отделяйте собственные метки и вычисляемые признаки от исходных полей и описывайте исключения, которые вызывают эти решения. Не приписывайте архиву собственные выводы о пригодности текста.

Важно понимать, что серверные ответы содержат плоские структуры данных, а не готовые древовидные сборки обсуждений. Когда в полученных записях присутствуют поля parent_id и link_id, клиентское приложение может сгруппировать их локально для построения иерархии комментариев. Однако сервер не гарантирует полноту цепочки родительских сообщений или наличие всех связанных сущностей, поэтому логика обработки должна учитывать эту особенность плоской архитектуры. Ответ содержит data, pagination и credits; поля могут отсутствовать. parent_id и link_id не являются фильтрами запроса. Отделяйте собственные исследовательские коды от исходного текста и не заполняйте отсутствующий контекст вымышленными значениями.

Границы страниц, итоги и обработка сбоев

Маршруты содержимого принимают limit и page от 1 до 100, по одной странице за запрос. Серия обращений не гарантирует 10000 разных записей или полного набора. Параметров массовой загрузки и случайного отбора нет. Разбиение дат и локальное удаление дублей организуют работу без доказательства полного охвата или уникальности. Сохраняйте ответы, использованные для анализа: повторные запросы не гарантируют тот же вход.

Читайте pagination.total вместе с relation: eq — точный итог запроса, gte — нижняя граница, unknown — отсутствие надёжного итога, возможно null. Пустая страница после первой может вернуть unknown, а не число ноль. Точный итог не доказывает скачивания всех совпадений или наличия всей истории в архиве. Сохраняйте has_more и window_exhausted как признаки границ, не токены неограниченного экспорта.

HTTP 400 относится к неправильным параметрам, 401 — к отсутствующему или недействительному ключу, 402 — к нехватке кредитов, 429 — к ограничению частоты. Некорректные запросы не списываются; сбой источника возвращает резерв. Успешное получение стоит один кредит, даже пустое и повторное. Потеря ответа может скрывать оплаченный успех; локальная ошибка не возвращает его стоимость. Сохраните ответ до обновления прогресса и учитывайте успешные повторы отдельно.

Маршруты API

Метод	Маршрут	Параметры
`GET`	`/v1/search`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/posts`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/comments`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/item`	`id`
`GET`	`/v1/subreddits`	`prefix, limit`
`GET`	`/v1/status`	`—`

Параметры запроса

Параметр	Значение / тип / диапазон
`q`	`text`
`subreddit`	`keyword`
`author`	`keyword`
`kind`	`post \| comment`
`from`	`ISO date`
`to`	`ISO date`
`min_score`	`integer`
`limit`	`1–100`
`page`	`1–100`
`id`	`item ID`
`prefix`	`subreddit prefix`