認証とHTTPエラー
保護された取得にはAuthorization: Bearer YOUR_API_KEYまたはX-API-Key: YOUR_API_KEYを指定できます。どちらも有効です。/v1/statusはキー不要で無料です。HTTP 401はキーの欠落または無効を意味し、アカウント画面のセッション期限とは別です。キーと残高はsubredditapi.com専用で、他ブランドのサイトでは使えません。
HTTP 400は不正なパラメータ、402は残高不足、429はレート制限です。400なら条件を修正し、401ならキーを調べ、402なら処理を止めるか残高を追加し、429なら待ってください。有効なキーだけで成功や特定の記録の存在が保証されるわけではありません。エラーと実際の取得応答を区別して保存します。
成功した取得は空結果でも1クレジットです。不正なリクエストは課金されず、取得元の失敗では予約分が返還されます。クライアントの通信断はサーバーの失敗と同じではなく、課金対象の成功が起きている場合があります。その後の成功した再試行も課金されます。無料の/v1/statusは検索の健全性や内容の範囲を確認しません。
ルートと検索パラメータ
GET /v1/searchはq、subreddit、author、kind、from、to、min_score、limit、pageを受け付けます。kindの値はpostまたはcommentです。GET /v1/postsとGET /v1/commentsは対応する種類の記録を取得します。既知の1件を調べるにはGET /v1/itemでidを指定します。idは投稿一覧やコメント一覧のフィルターではありません。
fromとtoはUTCの暦日をYYYY-MM-DDで指定し、toの日を含みます。limitとpageは1から100までで、1回100件、1クエリ100ページが上限です。min_scoreはフィルターであって並べ替えではありません。結果はアーカイブ文書順であり、日時、関連性、スコアの順ではありません。繰り返しても全件を取得できる保証はありません。
GET /v1/subredditsはprefixとlimitでコミュニティ名を探索します。集計数を全体の正確な件数とみなさないでください。取得の総数関係はeqが正確、gteが下限、unknownが不明を示し、総数がnullの場合もあります。正確な総数でもクライアントが全記録を受信した証拠にはなりません。これらの情報を元の応答と一緒に残します。
レコード構造と比較の限界
レスポンスはフラットなレコードであり、完成したスレッドツリーではありません。parent_idとlink_idがあればローカルで関連付けられますが、完全な祖先や会話は保証されません。これらは公開された検索フィルターではありません。引用に必要な文脈が欠けていれば、その欠落を明記し、別の記録から推測で補わないでください。
サービスは独立した履歴アーカイブであり、Reddit OAuth、投稿、投票、非公開メッセージやライブ監視を提供しません。過去のデータでも固定されたスナップショットとは限りません。比較対象の各コミュニティには個別にリクエストを送り、他の条件を揃えます。条件が一致しても範囲の偏りがなくなるわけではありません。
小さな例は/v1/search?q=soil&subreddit=gardening&limit=3です。受信した文章に対する語彙集計、テーマ分類、感情分析は利用者側の作業で、APIが指標を作るわけではありません。文章の欠損、除外条件、言語混在の処理を記録してください。保存済み応答への同じ手順の適用は検証できますが、将来同じ検索結果が出るという意味ではありません。
