エントリ：API
DRチェッカーツールAPI：すべてのパラメータとフィールドの解説
リクエストの形式と、認証済みレスポンスに含まれる2つのフィールドの参照。アクション固有の行は異なるため、解析する前に1回呼び出しをテストしてください。
このサービスはJSONを返すREST APIです。CORSは開放されています。ブラウザページから直接呼び出すことができます。キーはsk_で始まり、Googleサインイン後のアカウントページから取得します。
ベースURLはhttps://rankupedia.com/api.phpです。クエリ文字列にkey=sk_...を指定するか、ヘッダーAuthorization: Bearer sk_...を使用して認証します。クライアントの好みに応じていずれかを選択してください。4つのアクション（domain、overview、stats、suggest）は認証を必要としません。
DRチェッカーツールは、その出力を解析できるようになって初めて有用になります。以下のサンプルは最も実用的な最小限のケースであり、その後のセクションでは一般的に誤解されやすい部分について解説します。
1回の呼び出しの注釈付き例
無料のoverviewアクション。ドメインを自分のものに変更してください。
curl "https://rankupedia.com/api.php?action=overview&q=nytimes.com"
# authenticated listing, 100 rows per page:
curl -H "Authorization: Bearer sk_live_..." \
"https://rankupedia.com/api.php?action=refdomains&q=nytimes.com&per=100&page=1&order=desc"リクエストの構造
ターゲットの名前指定
qの値は、スキームやパスを含まない裸のドメイン（例：nytimes.com）です。
有料アクションの場合は資格情報を追加
クエリ文字列内のkey、またはBearerヘッダーのいずれかを使用します。ヘッダーを使用すると、キーがサーバーログやブラウザの履歴に残らなくなります。
ページ送りとソート
pageとperで結果を分割し、sortとorderで並び替えます。ページネーションは50,000行までです。
最初の呼び出し前のドメインリストの準備
多くの奇妙な結果は、サーバーではなく入力データに起因します。リストを一度クリーンアップしてから送信してください。
裸のドメインではないものはすべて削除します。パス付きで貼り付けたアドレスは、q値が想定していない文字を追加するため、スキーム、パス、末尾のスラッシュを削除してください。
スキームとパスを削除
https://shop.example.org/blog/ を呼び出し前に shop.example.org に変換します。q値は裸のドメインのみを受け取るため、パスは送信するのではなくここで削除されます。
スプレッドシートではこれらの詳細がセル内に隠れます。スラッシュやコロンをフィルタリングする簡単な操作で、そのほとんどを検出できます。
名前を小文字に変換し、重複を削除
ドメイン名は大文字小文字を区別しないため、Example.COMとexample.comは同じターゲットを指します。両方を送信すると、1つの回答に対してクレジットが2回消費されます。
呼び出し数を数える前に重複を削除してください。300件の重複を含む2,100件のリストは、生データでは2回のbulk_dr呼び出しが必要ですが、重複を削除した1,800件の一意な名前であれば1回で済みます。
ルートドメインとサブドメインの選択
blog.example.orgのようなサブドメインは、リスト内で独自の名称となります。何かを送信する前に、質問がどちらを指しているか決定してください。
質問がサイト全体をカバーする場合はルート名を送信します。1つのサブドメインのみをカバーする場合は、その正確な名前をテストし、回答をそのサブドメイン固有のものとして読み取ってください。
決定をジョブのノートに記録してください。これにより、次の実行時（おそらく別の担当者による）に同じルールが適用されます。
クエリパラメータ
| パラメータ | 意味 | 備考 |
|---|---|---|
| action | 実行する操作 | 必須；cost tableを参照 |
| q | ターゲットドメイン | 例：nytimes.com |
| key | APIキー | またはBearerヘッダーを使用 |
| page | 結果のページ番号 | 深いページネーションは50,000で制限されます |
| per | ページあたりの行数 | 10から5000まで受け付けます。行数に関係なく、1回の呼び出しが1回の課金となります |
| sort | ソート対象の列 | 利用可能な列はアクションによって異なります |
| order | ascまたはdesc | sortと共に使用 |
| domains | bulk_dr用のリスト | 1回あたり最大2,000ドメイン、GETまたはPOSTボディ経由 |
長いリストのページネーション
リスト表示アクションはページ単位で行を返します。2つのパラメータで分割を制御します：pageでどのスライスを選択するか、perでそのスライスに何行保持するかを指定します。perは10から5000の値を受け付けます。
まずページサイズを選択してください。大きなper値は呼び出し回数を減らし、課金は行数ではなく呼び出し回数に基づきます。
ページ送りの前にソート
sortとorderは、どの行が1ページ目に来るかを決定します。一連の呼び出しでは毎回両方を設定し、各ページが同じ順序付けに基づいて取得されるようにしてください。
最も強い行を先に表示したい場合はメトリック列にdescを、最も弱い行を探したい場合はascを使用します。利用可能な列名はアクションによって異なります。
長い処理を信頼する前に、2ページの小さなテストで順序を確認してください。
50,000行の上限で停止
深いページネーションは50,000行で停止します。それ以降は新しいデータが返されないため、ページネーションを続けるループはクレジットの無駄遣いになります。
質問を絞り込むか、タスクを小さな実行単位に分割してください。異なるターゲットで2回目のクエリを実行する方が、より深いページを取得するよりもクリーンな結果になります。
深度の上限はリストのプロパティであるため、それを使用するすべてのクライアントに適用されます。
短いページでループを終了する
ページが1件あたりの行数よりも少ない行数を返した場合、処理を停止します。これはリストのデータが尽きたことを示す一般的な兆候です。
このテストをトラブルシューティングのエントリの残高確認と組み合わせ、残高が底をつくか最後のページに到達するまで、いずれか早い方でループを終了します。
すべてのレスポンスに含まれるフィールド
ok
ブール値です。Trueは呼び出しが完了したことを、Falseは完了しなかったことを示し、HTTPステータスコードがその理由を伝えます。
_credits
認証済み呼び出しに表示されます。この呼び出しのコストと、クレジットでの残高残高を報告します。これにより、残高が尽きる前にループを終了できます。
各アクションの行レベルのフィールド名は、実際のレスポンスで確認できます。サービスとの乖離を防ぐため、このエントリにはそれらを再掲載しません。
ループを書く前の呼び出しテスト
よく知るドメインを選ぶ
自身のページからプロファイルの評価が可能なサイトを選びます。よく知るドメインであれば、奇妙な数値も容易に見つけられます。
無料の呼び出しを1回送信する
APIキーなしでoverviewまたはdomainを実行します。レスポンスはJSONの実際の構造を示し、この説明を含む他のどの記述よりも信頼性が高いです。
最小ページの有料呼び出しを1回送信する
リストアクションでper=10を使用します。スケーリングする前に、行フィールドと_creditsの値を確認できます。
_creditsを読み取り、その後スケーリングする
1回呼び出しのコストにプラン内の呼び出し回数を掛けます。合計が残高を超える場合、ループ開始前にプランを縮小します。
クライアントのデプロイ前
- 他のフィールドを読む前にokを確認する
- すべての呼び出しで_creditsをログに記録する
- データを月次スナップショットとして扱う
- 401と402を個別に処理する。トラブルシューティングのエントリを参照
- APIキーをフロントエンドコードから分離する
バッチ処理に関するメモ
bulk_drアクションは1回の呼び出しで最大2,000ドメインを受け付けます。リストがURLに収まらない場合はdomainsクエリ値として、またはPOSTボディとして送信します。
compareは最大20ドメイン、intersectは2〜10ドメインを受け付けます。intersectは1つの質問に答えます：指定したすべてのドメインにリンクしているサイトはどれか。
課金は呼び出し単位であるため、バッチが大きいほど1行あたりのコストは安くなります。また、バッチ全体が失敗します。再試行可能なサイズでチャンク化してください。
長いリストはPOSTボディに含めることができます。拒否されたバッチには使用可能な行が含まれないため、レスポンスの他の内容よりも先にokを確認してください。
前提条件なしでJSONを読み取る
パーサーはレスポンスに含まれていないフィールドで失敗します。すべての行にすべてのキーが存在することを前提としたコードは脆弱であり、1行でも短い行があれば、全体のタスクが停止する可能性があります。
欠落フィールドを正常な状態として扱う
行フィールドはアクションによって異なるため、あるリストに含まれるフィールドが別のリストには存在しない場合があります。各フィールドにデフォルト値を設定し、処理を続行してください。
失敗しただけでなく、どのフィールドが欠落していたかをログに記録してください。そのログにより、スキーマ自体が変更されたのか、それとも自前のコードが変更されたのかが判断できます。
サンプルの生レスポンスを保持する
新しいジョブの最初の数回呼び出しにおける生JSONを保存してください。後で数値がおかしいと判断された際、保存されたテキストは記憶よりもはるかに迅速に問題を解決します。
サンプルには日付とアクション名を合わせて保存してください。月次で更新されるため、同じ呼び出しでも翌月には異なる行が返される可能性があります。
アクションの分類
| 分類 | アクション | 一般的な用途 |
|---|---|---|
| 無料 | domain, overview, stats, suggest | クイックルックアップとオートコンプリート |
| スコアリング | bulk_dr, compare, dr_distribution | リストのスクリーニングとピアセットの作成 |
| リスト表示 | refdomains, backlinks, anchors, toppages, anchor_cloud | 単一サイトの監査 |
| 検索 | search, keyword, intersect | 特定のアンカーテキストや複数の競合他社へのリンク元を特定する |
行レベルのフィールド名はアクションによって異なり、ここでは一覧にしていません。既知のドメインに対して無料アクションを呼び出し、JSONを読み取ってください。JSONが唯一の権威ある情報源です。
開発者がよく質問するパラメータに関する事項
APIの初週でよく聞かれるパラメータに関する質問は4つに収まります。
すべての呼び出しにキーが必要ですか？
いいえ。domain, overview, stats, suggest アクションにはキーは不要です。有料アクションにはキーが必要で、key パラメータまたは Bearer ヘッダーとして送信します。
URLにキーを含めても大丈夫ですか？
はい。key パラメータはクエリ文字列でも機能します。ヘッダーを使用すれば、キーがURL自体に含まれないため、ログや共有リンクにおいて多くのチームが好む方法です。
5000より大きい値を指定したい場合はどうすればよいですか？
文書化されている範囲は10から5000です。この範囲外の値は本エントリで説明する対象外となるため、値を範囲内に保ち、ページネーションで追加データを取得してください。
q パラメータの大文字小文字は区別されますか？
ドメイン名は大文字小文字を区別しないため、送信前に値を小文字に変換してください。統一されたスペルにより、実行間での結果比較が容易になります。
