Защищённое чтение и публичный статус
Защищённое чтение использует GET на https://api.getredditdata.com с X-API-Key: <ключ> либо Authorization: Bearer <ключ>. Оба варианта передают ключ архива этого домена, а не токен Reddit OAuth. Храните секрет на сервере. Cookie Secure HttpOnly личного кабинета относится к отдельной сессии и не заменяет заголовок получения данных. Архив независимый и исторический, без официальной связи с Reddit и обновлений в реальном времени.
/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 — внутренний порядок документов, не хронология, релевантность или оценка. Высокий порог не подтверждает качество совета или представительность группы. Локальная сортировка организует только полученное; она не доказывает, что все более ранние записи уже найдены или будут доступны при следующем обращении.
Все ответы API содержат плоские записи, а не собранные сервером древовидные структуры. Если поля parent_id и link_id присутствуют в возвращаемых записях, клиент может сгруппировать их локально, но это не гарантирует наличия полного контекста беседы или полной родословной. Фильтры по этим идентификаторам также не представлены в интерфейсе запроса напрямую. Ответ содержит data, pagination и credits. Поля могут отсутствовать или различаться: отмечайте это в локальной таблице, а не подставляйте значения, которых не было в ответе. Собственные метки и преобразования храните отдельно от исходного текста.
Границы страниц, итоги и обработка сбоев
Маршруты содержимого принимают limit и page от 1 до 100, по одной странице за запрос. Серия обращений не гарантирует 10000 разных записей или полный набор. page=101 для той же выборки не поддерживается. Разбиение дат и локальное удаление дублей организуют сбор, но не доказывают охват, уникальность или неизменность повторной выдачи. Сохраняйте фактические ответы, на которых основан анализ.
Читайте pagination.total вместе с relation: eq — точный итог запроса, gte — нижняя граница, unknown — отсутствие надёжного итога, возможно null. Пустая страница после первой может вернуть unknown, а не число ноль. Точный итог не доказывает скачивания всех совпадений или наличия всей истории в архиве. Сохраняйте has_more и window_exhausted как признаки границ, не токены неограниченного экспорта.
HTTP 400 относится к неправильным параметрам, 401 — к отсутствующему или недействительному ключу, 402 — к нехватке кредитов, 429 — к ограничению частоты. Некорректные запросы не списываются; сбой источника возвращает резерв. Успешное получение стоит один кредит, даже пустое и повторное. Потеря ответа может скрывать оплаченный успех; локальная ошибка не возвращает его стоимость. Сохраните ответ до обновления прогресса и учитывайте успешные повторы отдельно.
