エンドポイントと認証
基点は https://api.subredditdata.com です。/v1/searchは過去の記録を検索し、/v1/postsと/v1/commentsは記録の種類を限定します。これらの一覧取得にidは不要です。/v1/itemは一件のidが必要です。/v1/subredditsはprefixとlimitで名前を探すもので、会員数や成長履歴を含む完全なプロフィールではありません。/v1/statusは公開され、課金されません。
保護された取得には、加工しないキーをX-API-Keyに設定するか、同じキーをAuthorization: Bearerで送ります。X-API-KeyにBearerを付ける必要はありません。キーと残高はsubredditdata.comのもので、別ドメインと共通ではありません。サイトのSecure HttpOnlyセッションCookieは、プログラムのAPI認証とは別です。
本文検索のパラメータはq、subreddit、author、kind、from、to、min_score、limit、pageです。kindはpostまたはcommentで、searchでは省略できます。qはtitleとtextを対象とし、解析後の複数語は一致するフィールド内でANDになります。両フィールドに全語が必要という意味でも、完全なフレーズ検索や任意の検索言語でもありません。
使える条件はエンドポイントごとに異なります。itemはid、subredditsはprefixとlimitを受け付け、未知の条件名はエラーになります。parent_id、link_id、感情、人口属性を指定する検索条件はありません。比較表には省略した条件も明記し、語の違いとそれ以外の条件変更を区別してください。
日付と記録の限界
日付は厳密にYYYY-MM-DDとし、created_utcをUTCで指定します。fromはその日の午前零時、toは23:59:59までを含みます。例としてfrom=2026-04-01とto=2026-04-30なら四月の暦日が対象です。今日をtoにしても一日全体が境界となり、送信時刻までには切り詰めません。未収録や将来の記録が返るという約束ではありません。
返されたレコードにはparent_idやlink_idが含まれる場合がありますが、それらはクライアント側でグループ化するためのものです。サーバー側では完全な会話履歴や祖先情報が保証されないため、クライアント側で適切に整理する必要があります。
limitとpageはそれぞれ1から100です。_doc順は日時、関連度、スコアの並びではありません。min_scoreはスコア下限であり、正しい発言を選ぶ機能ではありません。最大ページまで進んでも網羅的な出力にはなりません。取得後に日時で並べ替えても、手元にない活動履歴が補われるわけではありません。
件数の関係はeqならその応答について正確、gteなら下限、unknownなら信頼できる合計がなくnullにもなり得ます。収録範囲や代表性を示す値ではありません。コミュニティ名の集計件数も全体で正確とは保証されません。手元の話題集計には実際に読んだ記録を使い、重複、除外、不明を別に示してください。
エラーと返答の紛失を区別する
HTTP 400は無効な要求、401はキーの欠落や無効、402は残高不足、429は頻度制限です。原因を直してから再試行し、エラーを「話題が存在しない」という結果に置き換えないでください。/v1/statusは静的なサービス説明とHTTP応答だけで、検索元の稼働や記録の可用性を検査しません。
成功した取得は空でも一クレジットです。無効な要求は引き落とさず、上流障害では予約したクレジットを返します。ただし、クライアントのタイムアウトや返答紛失時にもサーバーでは成功し、課金済みの可能性があります。成功した再試行は別の課金です。成功後に手元の処理が失敗しても最初の料金は取り消されません。
