Защищённое чтение и публичный статус
Защищённое чтение использует GET на https://api.redditstreamapi.com с X-API-Key: <ключ> либо Authorization: Bearer <ключ>. Оба варианта передают ключ архива этого домена, а не токен Reddit OAuth. Храните секрет на сервере. Cookie Secure HttpOnly панели счёта относится к отдельной сессии. Сервис возвращает отдельные JSON-ответы, а не живой SSE-поток, соединение WebSocket или подписку на события 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 — внутренний порядок документов, не время вставки, хронология, релевантность или оценка. Последняя запись страницы не является гарантированной временной отметкой прогресса. Локальная сортировка организует полученное, но не доказывает, что все более ранние записи уже загружены, а поздние появятся в будущем обращении.
Записи содержимого плоские, поля могут различаться. Присутствующие parent_id и link_id допускают локальную группировку, без полной цепочки родителей или беседы. Ни одно поле не является фильтром запроса. Ответы содержат data, pagination и credits. Проверяйте полученные данные, сохраняйте отсутствие полей и неразрешённые ссылки вместо подстановки вымышленных значений для собственной схемы. Успешный пустой массив data не является ошибкой аутентификации.
Границы страниц, итоги и обработка сбоев
Маршруты содержимого принимают limit и page от 1 до 100, по одной странице за запрос. page=2 не возвращает первую и вторую страницы вместе. Нумерация не является стабильным курсором или последовательностью событий; page=101 для той же выборки не поддерживается. Дробление окон и локальное удаление дублей организуют работу, не доказывая полного охвата, уникальности или неизменности повторного результата.
Читайте 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 |
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 |
curl -H "Authorization: Bearer YOUR_API_KEY" 'https://api.redditstreamapi.com/v1/search?q=research&limit=10'
import json, urllib.request
request = urllib.request.Request('https://api.redditstreamapi.com/v1/search?q=research&limit=10', headers={"Authorization": "Bearer YOUR_API_KEY"})
with urllib.request.urlopen(request) as response:
print(json.load(response))
fetch("https://api.redditstreamapi.com/v1/search?q=research&limit=10", {headers: {Authorization: "Bearer YOUR_API_KEY"}})
.then(response => response.json()).then(console.log);