Відокремте контракт API від схеми власного результату

Маршрути, фільтри, автентифікація та HTTP-помилки Reddit Extract. Як перевіряти необов’язкові поля й типи перед локальним перетворенням.

Отримати API-ключ

Маршрути мають різні завдання

API Reddit Extract пропонує доступ до історичної архівної бази даних Reddit через чітко визначені маршрути HTTP. Ключові ендпоінти включають /v1/search для пошуку, /v1/posts і /v1/comments для отримання конкретних типів контенту, а також /v1/item для детальних записів. Цей набір інструментів дозволяє розробникам ефективно витягувати структуровані дані для подальшої аналітики чи трансформації.

Базовий хост — https://api.redditextract.com. Для захищеного читання передайте ключ цього домену в X-API-Key або Authorization: Bearer. Це не токен Reddit OAuth; cookie входу в кабінет не замінює заголовок API. /v1/status є публічним і нетарифікованим: він повідомляє статичний опис сервісу та відповідь HTTP-сервера, а не стан пошуку, баланс чи наявність потрібних записів.

Запити до /v1/search, /v1/posts і /v1/comments не потребують id. Для /v1/item потрібен id однієї архівної сутності, яка може бути відсутня. /v1/subreddits підтримує prefix і limit для пошуку спільнот, а не весь набір фільтрів вмісту. Для вмісту доступні q, subreddit, author, kind, from, to, min_score, limit і page. Значення kind — post або comment; межі limit і page — 1–100.

Перевірка полів замість припущення про сталу схему

Дати from і to задаються як YYYY-MM-DD в UTC та фільтрують created_utc; увесь день to включається. min_score використовується лише як фільтр; порядок _doc не є хронологічним, релевантним або впорядкованим за рейтингом. Немає параметрів fields, parent_id чи link_id для відбору відповіді. У прикладі q=index&subreddit=PostgreSQL&limit=3 вибір потрібних стовпців виконує ваш застосунок уже після отримання невеликої сторінки.

Відповідь містить плоскі записи. Для кожного потрібного значення перевірте наявність властивості та її тип; не ототожнюйте пропуск із null або порожнім рядком. Поле title, text, author, score чи created_utc, якщо воно є, треба перевірити перед використанням. Це перелік можливих входів для ваших правил, а не гарантія того, що вони наявні в кожному дописі чи коментарі.

Ідентифікатори зберігайте без довільного числового перетворення. Для часу спершу встановіть формат і одиниці, а для рейтингу — числовий тип. Локальні назви на кшталт record_id та body_text описують вашу вихідну схему, а не новий контракт API. Посилання parent_id і link_id можна використати для локального поєднання, але сервер не гарантує повного набору пов’язаних записів.

Пагінація, помилки та вартість повтору

На сторінці може бути до 100 записів, а один набір умов обмежений 100 сторінками. Це не гарантує повного експорту. Відношення eq означає точний підсумок, gte — нижню межу, unknown — відсутність надійного підсумку, який може бути null. Не використовуйте обмежений лічильник як загальну кількість усіх відповідних обговорень у Reddit.

HTTP 400 означає некоректний запит, 401 — відсутній або недійсний ключ, 402 — недостатній баланс, 429 — обмеження частоти. Виправляйте причину до повтору. Помилка локального перетворення після успішної відповіді не змінює статус отримання. Збережений вхід допомагає виправити правила без додаткового виклику API й без підміни фактичних значень здогадками.

Успішне отримання коштує один кредит, включно з порожньою сторінкою. Відхилений до отримання даних запит не купує записів, а помилка джерела повертає зарезервований кредит. Повторний успішний виклик може витратити ще один кредит; повторний розбір локального файлу — ні. Баланс саме цього домену перевіряйте в кабінеті на сторінці ключа, а не через /v1/status.

Маршрути 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, limit`
`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`