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