---
title: "検索順位チェック登録"
method: POST
path: "/v1/search-rank"
tags: ["検索順位チェック"]
---

# 検索順位チェック登録

`POST /v1/search-rank`

検索順位チェック登録。
Google検索における検索順位および、KWの月間検索数/SEO難易度を取得できる（isSearchVolumeAndSeoDifficultyEnabledがONの場合）。
キーワードリストとURL/ドメインを渡すと非同期で検索順位を調査開始する。

処理はバックグラウンドで行われるため、以下の手順で結果を取得すること:
1. 戻り値の requestId を控える
2. GET /v1/search-rank/{requestId}/status で完了を待つ（ポーリング推奨: 初回は30秒後、以降30秒間隔）
3. isCompleted=true になったら POST /v1/search-rank/{requestId}/results で結果を取得する

通常は10件以内は数分以内、それ以外は60分以内程度で取得される。
混雑時は数時間以上かかる場合もあるため、数分経過しても処理が完了しない場合は、
一定の時間を置いてから処理ステータスを確認することを推奨する。

1キーワードあたり0.9クレジットを消費（1〜30位取得）。31〜100位まで取得範囲を拡張する場合は、取得範囲を10位追加するごとに、1キーワードあたり0.3クレジットを追加消費する。

## Request body

- SearchRankHistoryDto
  - `keywords` string[], required — 順位チェックするキーワードの配列
  - `urls` string[], required — 順位チェックするURL/ドメインの配列。最大50件まで指定可能。
  - `matchType` 'url' | 'forward_url' | 'domain' | 'sub_domain' — マッチタイプ。url: 完全一致URL / forward_url: 前方一致URL / domain: ドメイン完全一致 / sub_domain: サブドメイン含むドメイン一致。省略時は sub_domain。
  - `depth` 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100 — 検索上位何位までデータ取得するかを指定する。30 / 40 / 50 / 60 / 70 / 80 / 90 / 100 のいずれかを指定。省略時は 30。
  - `isSearchVolumeAndSeoDifficultyEnabled` boolean — 月間検索数/SEO難易度を取得するかどうか。省略時は false。
  - `deduplicate` boolean — キーワードの重複除去を行うかどうか。省略時は true。
  - `location` string — SERP取得対象の地域名。省略時は Japan。 - 指定可能な地域名は metadata の locations 一覧を参照（一覧は国レベルのみ） - 市区町村レベルの地域も指定可能。「市区町村名,上位地域名,国名」のようにカンマ区切りの正式名で指定する（例: Shibuya,Tokyo,Japan） - 途中の階層のみ（例: 都道府県のみ）の指定は未サポート
  - `language` string — SERP取得対象の言語名。指定可能な言語名は metadata の languages 一覧を参照。省略時は Japanese。
  - `device` 'desktop' | 'mobile' — SERP取得対象のデバイス。desktop / mobile のいずれか。省略時は desktop。
  - `os` 'windows' | 'macos' | 'android' | 'ios' — SERP取得対象のOS。デスクトップは windows / macos、モバイルは android / ios を指定。省略時は desktop→windows / mobile→android。

## Response `201`

登録成功

- SearchRankHistoryResponseDto
  - `result` boolean, required — API 呼び出しの成否。正常時は true、エラー時は false。
  - `meta` object, required — リクエストに関するメタ情報（課金・消費リソースなど）
    - `consumedCredit` number, required — このリクエストで消費されたクレジット数。
  - `data` object, required — 履歴登録結果
    - `requestId` string — リクエストID
  - `errors` string[], required — エラーメッセージの配列。正常時は空配列。

## Other responses

- `400` — バリデーションエラー
- `402` — クレジット不足
- `403` — 認証エラー
- `429` — レート制限超過
- `500` — Internal Server Error
- `503` — Service Unavailable - データベース接続エラーなど

---

[API](https://skmtc.dev/rakkokeyword/apis/api.md) · [All operations](https://skmtc.dev/rakkokeyword/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rakkokeyword/api/revisions/23e921f5f25c/schema)