Ключ и маршруты для чтения
Базовый адрес — https://api.redditlistening.com. Передавайте ключ этого домена в X-API-Key без префикса либо используйте альтернативный заголовок Authorization: Bearer с тем же ключом. Это два поддерживаемых способа аутентификации API. Сессионная cookie кабинета служит входу на сайт и не заменяет ключ в программе. Не вставляйте действующий ключ в публичную страницу, пример отчёта или общий журнал выполнения.
Маршрут /v1/search ищет исторические записи; /v1/posts и /v1/comments позволяют обращаться к соответствующим видам материалов. /v1/item требует id конкретной записи. /v1/subreddits использует prefix для поиска имён сообществ и limit для ограничения ответа. Общедоступный /v1/status сообщает статическое описание исторического сервиса; его успешный ответ не подтверждает исправность поиска, доступность архива или живое соединение с Reddit.
Для поиска содержимого предусмотрены q, subreddit, author, kind, from, to, min_score, limit и page; kind различает post и comment. Набор параметров зависит от маршрута: не переносите все фильтры поиска в запрос item или subreddits. Произвольный язык запросов, фильтр настроения, рыночной доли, региона или языка этим интерфейсом не обещаны. Проверяйте параметры до массового выполнения, а не считайте неизвестное имя фильтра проигнорированным. Параметр q ищет по архивным полям title и text, то есть по заголовку и тексту записи.
Даты, записи и пределы выдачи
Фильтры from и to принимают только дату YYYY-MM-DD по UTC и сравниваются с created_utc. Начало периода — начало суток from, конец включает сутки to до 23:59:59 UTC. Например, from=2026-04-01 и to=2026-04-30 задают апрельские календарные сутки, а не местное время браузера. Если to указывает сегодня, включены целые текущие сутки UTC, не только время до запроса; это правило границы, а не обещание наличия будущих или ещё не поступивших записей.
Важно понимать, что ответ API содержит плоские записи, а не собранные древовидные структуры комментариев, которые можно встретить в веб-интерфейсе Reddit. Хотя поля идентификатора родителя и ссылки могут присутствовать в ответе, клиент должен самостоятельно группировать данные, если это необходимо, так как полнота иерархии не гарантируется. Запрос конкретного элемента требует обязательного указания идентификатора, в то время как поиск постов и комментариев осуществляется без него.
Порядок _doc не является сортировкой по времени, популярности или релевантности. Ограничение min_score оставляет записи с подходящей оценкой Reddit, но не измеряет эмоциональную окраску. Максимум составляет 100 записей на запрос и 100 страниц для одних условий поиска. Даже достижение последней доступной страницы не доказывает исчерпывающего охвата темы; изменение фильтров создаёт другую подборку, а не подтверждение полноты прежней.
Указатель общего количества тоже требует оговорки: отношение eq означает точное значение для ответа, gte — нижнюю границу, unknown — отсутствие надёжного итога. Не вычисляйте доли рынка из такого счётчика. Для локальной доли тем используйте количество реально прочитанных и размеченных записей, отдельно учитывая дубликаты, пропуски и неопределённые случаи. Не предполагайте, что каждое необязательное поле присутствует или содержит непустое значение.
Ошибки, оплата и воспроизводимые заметки
HTTP 400 указывает на некорректные параметры, 401 — на отсутствующий или недействительный ключ, 402 — на недостаточный баланс, 429 — на ограничение частоты. Сохраняйте код ответа и условия запроса без секрета; не заменяйте ошибку пустой исследовательской выборкой. Повтор запроса должен быть осмысленным: исправьте параметры или причину отказа прежде, чем продолжать чтение следующих страниц.
Успешное извлечение расходует один кредит даже при пустом результате. Некорректный запрос не списывает кредит; при сбое вышестоящего источника резерв возвращается. Если успешный ответ уже получен, ошибка вашей локальной разметки не отменяет стоимость. Повторное чтение сохранённого файла не требует API. Разделяйте протокол получения данных и собственную интерпретацию, чтобы смена кодировочной схемы не выглядела изменением исторического источника. Кредит списывается за успешное выполнение на сервере, даже если ответ не дошёл до клиента. Каждый успешный повтор расходует ещё один кредит, включая успешный ответ без записей.
