ルートと認証を選ぶ
データ取得先のホストはapi.redditsearchapi.comです。GET /v1/searchは一般的な検索、/v1/postsは投稿、/v1/commentsはコメントの取得に使います。識別子で単一の記録を取得する場合は/v1/itemにidを指定します。投稿とコメントの一覧にidは必須ではありません。/v1/subredditsではprefixによるコミュニティ名の前方一致検索ができます。
取得リクエストには、このドメインで作ったキーをX-API-Keyヘッダーで送信します。アカウントパネルのセッションCookieはAPIキーの代わりになりません。共有可能な検索URLや利用者向けエラー文にキーを含めず、認証設定と検索条件を分けて管理してください。認証の調査では、秘密の値を公開せずヘッダーの有無や設定を確認します。
GET /v1/statusは公開されており、クレジットを消費しません。独立した過去データのアーカイブというサービス範囲を静的に示し、HTTPサーバーが応答したことを確認できます。検索基盤の健全性、記録の利用可能性、データの網羅性を検査するものではありません。成功した応答を、検索機能全体の正常性と同一視しないでください。
検索条件と総件数を読む
対応する検索パラメーターはq、subreddit、author、kind、from、to、min_score、limit、pageです。kindの値はpostまたはcommentです。fromとtoはUTCを基準にYYYY-MM-DD形式で送り、toは指定日を含みます。画面上の日付表示を地域に合わせる場合も、APIへ渡す実際の日付範囲を確認できるようにします。
limitとpageの指定範囲はそれぞれ1～100です。1回の呼び出しは最大100件の1ページを返し、次のページには別のリクエストが必要です。100ページが一度に返るわけではありません。日付やコミュニティでクエリを分けることは作業の整理には役立ちますが、重複のない取得や全件取得の証明にはなりません。
総件数の関係を表すeqは正確な一致件数、gteは下限、unknownは信頼できる総件数が不明であることを示します。総件数がnullの場合もあります。クエリの件数が正確でも、Reddit全体がアーカイブされているとは限りません。下限を確定件数として集計したり、不明な総件数をゼロに置き換えたりしない設計が必要です。
取得順はアーカイブ内部の_doc順です。日付、関連度、スコアによる並べ替えではありません。min_scoreはスコアの最低条件としてのみ働きます。parent_idやlink_idが返された場合はローカルでグループ化できますが、これらを直接指定する検索フィルターはありません。各フィールドの存在を確認しながら平坦なレコードを処理してください。
エラーと再試行の費用
400は無効なリクエスト、401はキーの欠落または無効、402はクレジット不足、429はレート制限を示します。400ではパラメーター、401ではヘッダー、402では残高を確認します。429には待機と回数を制限した再試行を検討してください。キーや残高の問題は、同じ設定で繰り返すだけでは解決しません。
無効なリクエストはクレジットを消費せず、上流の処理失敗では予約されたクレジットが戻ります。成功した空の応答は課金対象です。サーバーで取得が成功した後にクライアント接続が切れた場合、すでに課金されている可能性があります。成功した再試行にも別途1クレジットが必要です。通信エラーだけで無料と判断しないでください。
