Доступ і призначення маршрутів
Використовуйте базову адресу https://api.redditlistening.com. Ключ цього домену передається в X-API-Key як є, без префікса, або в альтернативному заголовку Authorization: Bearer з тим самим ключем. Сеанс кабінету на сайті використовує окрему 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, а не тільки час до запиту. Це визначення межі фільтра, не обіцянка наявності майбутніх або ще не доступних записів.
Матеріал повертається плоскими записами. Необов’язкові поля можуть бути відсутніми чи порожніми; не підставляйте вигадане значення замість пропуску. За наявності parent_id або link_id їх можна використати для локального зіставлення, але це не відновлює відсутні частини розмови. Відрізняйте текст автора від цитати й позначайте випадки, коли без батьківського повідомлення неможливо зрозуміти об’єкт оцінки.
Порядок _doc не є сортуванням за часом, популярністю чи релевантністю. min_score — лише поріг оцінки Reddit. Один запит повертає щонайбільше 100 записів; для заданого пошуку доступно не більше 100 сторінок. Після останньої сторінки не можна оголосити добірку вичерпною. Нові слова пошуку можуть додати матеріал, але не доводять, що пропущених згадок більше немає.
Для загальної кількості eq означає точне значення, gte — нижню межу, unknown — відсутність надійного підсумку. Не використовуйте невідомий або обмежений підсумок як знаменник ринкової частки. Для власної розмітки рахуйте фактично прочитані записи та окремо перелічуйте виключені, повторні й невизначені випадки. Це кількість текстів у вашій роботі, а не кількість незалежних споживачів.
Відмова запиту не є результатом дослідження
Система повертає стандартні HTTP-коди для керування станом запиту. Помилка 401 означає відсутність або недійсність ключа автентифікації. Помилка 402 виникає, коли на вашому рахунку недостатньо кредитів для виконання запиту. У разі перевищення ліміту частоти запитів сервер повертає код 429. Усі ці коди є літеральними ASCII-числами, і їх слід обробляти відповідно до специфікації протоколу без локалізації.
HTTP 400 вимагає перевірити параметри; не перетворюйте його на «згадок немає». Успішне отримання витрачає один кредит навіть за порожнього результату. Некоректний запит не списує кредит, а за збою джерела зарезервований кредит повертається. Помилка вашого обробника після успішної відповіді не скасовує її вартість. Зберігайте умови пошуку, код відповіді та фактичний матеріал, щоб відрізняти технічну спробу від дослідницької інтерпретації. Кредит списується за успішне виконання на сервері, навіть якщо відповідь не дійшла до клієнта. Кожна успішна повторна спроба витрачає ще один кредит, зокрема за порожнього результату.
