---
title: "一括キーワード調査登録"
method: POST
path: "/v1/search-volume"
tags: ["一括キーワード調査"]
---

# 一括キーワード調査登録

`POST /v1/search-volume`

一括キーワード調査登録。
キーワードリストを渡すと非同期で月間検索数・SEO難易度・CPC・競合性などを調査開始する。

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

通常は10秒程度で取得完了するが、seoDifficultyをONにした場合、最大60分程度時間がかかる。
ONの場合、一定の時間が経過してから処理ステータスを確認することを推奨する。
SEO以外の目的で当機能を使う場合、時短のためseoDifficultyをOFFすることを推奨する。

1キーワードあたり0.03クレジットを消費。seoDifficultyがONの場合、追加で1キーワードあたり0.75クレジットを消費する。ただし、1リクエストの消費クレジットの合計が15クレジットに満たない場合は15クレジットを消費する。

## Request body

- SearchVolumeHistoryDto
  - `keywords` string[], required — キーワード（入力上限50,000件）
  - `seoDifficulty` boolean — SEO難易度取得フラグ。true の場合にSEO難易度を取得する。省略時は false。
  - `dataCompletion` boolean — データ補完フラグ。true の場合にデータ補完を行う。省略時は true。
  - `location` string — 地域名。省略時は Japan。 - 指定可能な地域名は metadata の locations 一覧を参照（一覧は国レベルのみ） - 市区町村レベルの地域も指定可能。「市区町村名,上位地域名,国名」のようにカンマ区切りの正式名で指定する（例: Shibuya,Tokyo,Japan） - 途中の階層のみ（例: 都道府県のみ）の指定は未サポート
  - `language` string — 言語名。指定可能な言語名は metadata の languages 一覧を参照。省略時は Japanese。
  - `deduplicate` boolean — キーワードの重複除去を行うかどうか。省略時は true。
  - `aggregationPeriodMonths` union — 集計期間（月数）。12/24/36/48 のいずれか。省略時は 12。
    - 12
    - 24
    - 36
    - 48

## Response `201`

登録成功

- SearchVolumeHistoryResponseDto
  - `result` boolean, required — API 呼び出しの成否。正常時は true、エラー時は false。
  - `meta` object, required — リクエストに関するメタ情報（課金・消費リソースなど）
    - `consumedCredit` number, required — このリクエストで消費されたクレジット数。
  - `data` object, required — 履歴登録結果
    - `requestId` number — リクエスト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)