APIルートの基本とレコード構造
独立したRedditアーカイブAPIは、自動化ワークフローに検索機能を組み込むための堅牢な基盤を提供します。このサービスは公式のRedditとは連携しておらず、過去のデータに特化したアーカイブです。主要なエンドポイントには/v1/search、/v1/posts、/v1/comments、/v1/item、/v1/subreddits、そして/v1/statusが該当します。これらのルートは、それぞれ検索、投稿、コメント、特定アイテム、サブレディット、そしてステータスチェックという異なる機能を提供します。
APIが返すデータはフラットなレコードであり、サーバー側でスレッド木や親子関係が組み立てられたものではありません。戻り値にparent_idやlink_idフィールドが含まれている場合、クライアント側でそれらをローカルにグループ化して関連付けることが可能です。ただし、それらが完全な会話やすべての親子関係を保証するわけではありません。サーバーが組み立てるスレッドツリーやparent_id・link_idの検索フィルターが存在しないため、データの利用にはクライアント側での処理が必要になります。
min_scoreは最小スコアによる絞り込みに使い、スコア順の並べ替えは行いません。結果はアーカイブ内の文書順（_doc）で返され、時系列、関連度、スコアの順ではありません。並び順から最新の投稿や重要な記録だと判断しないでください。必要な表示順への並べ替えは、実際に取得した記録に対して利用者側で行います。
クエリパラメータと制限事項
検索エンドポイントでは、q、subreddit、author、kind、fromとtoの日付、min_score、limit、pageなどの多様なフィルターが利用可能です。kindパラメータにはpostとcommentの値が指定できます。特定のエンドポイントでは制限が異なります。例えば/v1/postsや/v1/commentsではidパラメータは必須ではありませんが、/v1/itemの検索には必ずidが必要です。サブレディット検索ではプレフィックスサポートも提供されており、柔軟な検索が可能です。fromとtoはUTCのYYYY-MM-DD形式で、toの日付も含まれます。qはtitleとtextを検索し、複数の語を一致する同じ項目内でAND条件として扱います。
リクエストごとの最大記録数は100件まで、またクエリあたりの最大ページ数は100ページです。これを超えるとエラーが発生するため、自動化プロセスではこれらの制限を考慮したページネーションロジックを実装する必要があります。アーカイブ文書の順序は時系列順ではないため、過去の投稿を時系列順で取得するには追加の処理が必要です。ページネーションをループさせても、完全なアーカイブカバレッジや全レコードの完全な取得を保証するものではないため、注意が必要です。
ページ情報の合計は関係と一緒に読みます。eqはその検索の正確な合計、gteは下限、unknownは合計不明でnullになり得る状態です。下限を正確な総数として扱わないでください。また、検索の合計が分かってもReddit全体の収録範囲は分かりません。許可されたページをすべて巡回しても、アーカイブの完全な取得を証明するものではありません。
エラー処理とアカウント管理
APIからのレスポンスには、リクエストの成功または失敗を示すHTTPステータスコードが含まれます。400は不正なリクエストを、401はキーが不正または不足していることを、402はクレジットが不足していることを、そして429はレート制限の超過 であることを示します。これらのエラーコードは、ローカライズされた数字や単語ではなく、必ずASCIIの数字として扱われます。自動化システムでは、これらのステータスコードを適切にキャッチしてエラー処理ロジックを実装する必要があります。特に429エラーが発生した場合は、再試行ロジックを慎重に設計する必要があります。
正常な取得は空の結果でも1クレジットを消費します。取得元の障害では予約されたクレジットが利用者の残高に戻り、不正なリクエストでは引き落とされません。/v1/statusは無料です。クライアントが応答を失った場合でも、サーバーでは成功して課金済みの可能性があります。再試行が成功すると別の1クレジットを消費するため、タイムアウトだけを根拠に返還されたと判断しないでください。
アカウントの作成や管理には、電子メールとパスワードが必要です。パスワードはUTF-8で12から72バイトの長さである必要があります。Googleログインやウォレット接続、ウォレットアドレスの入力はサポートされていません。支払い前のサインアップ直後にAPIキーが一度だけ表示され、その後は再表示されません。パスワードの確認を行った後にのみAPIキーを再生成できます。再生成すると古いキーは直ちに無効化されます。アカウントパネルはキー取得ページに統合されており、別のダッシュボードURLは提供されないため、取得リクエストではAuthorization: BearerまたはX-API-Keyを使ってください。
