認証とエンドポイント
取得リクエストはGETで送信し、Authorization: Bearer <key>またはX-API-Key: <key>のいずれかを指定します。両方とも利用できる方式です。キーはredditlistening.comのアカウントに属し、別ドメインのキーでは代用できません。アカウント画面のSecure HttpOnlyセッションCookieと、データ取得用のキーは別の仕組みです。
/v1/search、/v1/posts、/v1/commentsで使える条件はq、subreddit、author、kind、from、to、min_score、limit、pageです。kindの値はpostまたはcommentです。postsとcommentsは種類を限定して取得するためのもので、idは不要です。個別の記録をidで探す場合は/v1/item?id=...を使います。この経路のパラメータはidです。
/v1/subredditsが受け付けるのはprefixとlimitだけです。日付やpageを指定する本文検索とは異なり、表示される件数も全体の正確な集計を保証しません。/v1/statusは認証不要で無料です。静的なサービス説明とHTTPサーバーの応答を示しますが、検索基盤の動作、記録の有無、アーカイブへのアクセス可否を検査するものではありません。
日付、順序、欠けている情報
fromとtoはUTCのYYYY-MM-DD形式で指定し、created_utcを絞り込みます。toは指定日の全体を含みます。今日のUTC日付を指定した場合も、今日の午前0時だけではなく一日全体が対象です。これは記録の作成日時であり、リュックを購入した日や故障が発生した日を検索する条件ではありません。
本文検索のlimitは1〜100、pageは1〜100です。返却順は_docで、時系列順、関連度順、スコア順ではありません。min_scoreは最低スコアによる絞り込みであり、並べ替えではありません。ページを最後まで巡回したり期間を分けたりしても、全件取得や重複のない完全な集合は保証されません。手元で並べ替えても対象は取得済みの記録だけです。
レコードはフラットで、会話ツリーとして組み立てられていません。parent_idやlink_idが存在する場合はローカルで関連付けられますが、これらは検索フィルターではありません。欠落したフィールド、null、空の文章を区別してください。合計の関係がeqなら正確、gteなら下限、unknownなら信頼できる合計がなく、値がnullの場合もあります。
エラーと研究用の取得記録
HTTP 400は不正なリクエスト、401はキーの欠落または無効、402はクレジット不足、429は頻度制限です。400なら日付形式と許可されたパラメータを、401ならキーを、402ならこのドメインの残高を確認します。429では待ってから再試行してください。未対応の条件を追加しても、会話の欠落部分や希望する並び順を取得できるわけではありません。
不正なリクエストは課金されず、取得元の障害では予約されたクレジットが戻ります。空でも成功した取得は1クレジットです。サーバーが処理を完了した後にクライアントが応答を失った場合は課金済みの可能性があり、成功した再試行にも別の1クレジットがかかります。受信失敗と、正常に受信した空の結果を同じものとして記録しないでください。
backpackとBuyItForLifeの例では、クエリ、取得時点、含めた記録、除いた理由を手元に残すと解釈を追えます。保存済みの文章を読み直すだけなら新しいAPI呼び出しは不要です。取得件数を購入者数に読み替えず、同じ人の複数コメントや複数製品への言及をどう扱ったかも研究方法に記載してください。
