---
title: "一括サイト調査"
method: POST
path: "/v1/bulk-site-research"
tags: ["一括サイト調査"]
---

# 一括サイト調査

`POST /v1/bulk-site-research`

一括サイト調査。

複数URL（最大100件）をまとめて調査し、各サイトの推定流入数・獲得キーワード数・ページ数などの現在値と、その推移（0〜100の指数）を取得する。
サイト群のSEO規模とトレンドを一括で把握するのに有用。

推移データ（histories）は、現在値スカラー（metrics）とは別ソース・別量のため、系列内最大月を100とする指数（0〜100・小数第2位）に正規化して返す。
etv / keywordCount / pageCount の3系列を各々独立に指数化し、キー名は etvIndex / keywordCountIndex / pageCountIndex とする（現在値との誤読防止）。
現在値・分布・変化率は実数のまま返す（指数化しない）。

urlMatchTypeで調査単位を指定する（url: 完全一致 / forward_url: 前方一致 / domain: ドメイン一致 / sub_domain: サブドメイン一致）。
itemsは入力urlsと同数・同順で返る。
対象URLは最大100件。

入力URL1件あたり0.45クレジットを消費（最低4.5クレジット）。（例: 10URL→4.5クレジット、100URL→45クレジット）。

## Request body

- BulkSiteResearchDto
  - `urls` string[], required — 一括サイト調査の対象URL一覧（1〜100件）。各URLの推定流入数・獲得キーワード数・ページ数の現在値と、その推移（0〜100指数）を取得する。
  - `urlMatchType` 'url' | 'forward_url' | 'domain' | 'sub_domain' — URLのマッチタイプ。url: 完全一致 / forward_url: 前方一致 / domain: ドメイン一致 / sub_domain: サブドメイン一致。省略時は domain。

## Response `200`

検索成功

- BulkSiteResearchResponseDto
  - `result` boolean, required — API 呼び出しの成否。正常時は true、エラー時は false。
  - `meta` object, required — リクエストに関するメタ情報（課金・消費リソースなど）
    - `consumedCredit` number, required — このリクエストで消費されたクレジット数。
  - `data` object, required — 一括サイト調査結果データ
    - `query` object, required — リクエストで指定されたクエリ情報
      - `targets` string[], required — urlMatchType で整形した検索対象パターン一覧（items と同数・同順）
      - `urlMatchType` 'url' | 'forward_url' | 'domain' | 'sub_domain', required — リクエストで指定された（または既定の）URLマッチタイプ
    - `summary` object, required — 件数サマリー（全体件数とレスポンスに含まれる件数。入力URLと1:1）
      - `totalCount` number, required — 取得対象全体の件数
      - `returnedCount` number, required — このレスポンスに含まれている件数
    - `items` object[], required — 一括サイト調査結果のリスト。入力 urls と同数・同順。
      - `site` object, required — 調査対象サイト（urlMatchType で整形した検索パターン）
        - `target` string, required — urlMatchType で整形した検索対象パターン（url: host/path / forward_url: host/path* / domain: host/* / sub_domain: *.host/*）
      - `metrics` object, required — 現在値の各種指標（実数）。推移の指数（histories）とは別量。
        - `estimatedTraffic` number, required — 推定検索流入数（月間・生値・現在集計）
        - `estimatedTrafficChangeRate` number, nullable, required — 推定流入数の前年同月比（生値ベース）。パーセントではなく比率（0.1 = +10%、1.0 = +100%）。算出不能時は null。
        - `keywordCount` number, required — 獲得しているキーワード数（生値）
        - `pageCount` number, required — インデックスされているページ数（生値）
        - `trafficValue` number, required — 集客価値の合計（USD・生値）。推定流入数×CPC で算出される広告換算価値。
        - `pagesWithTrafficCount` number, required — 検索流入があるページ数
        - `pagesWithTrafficRate` number, required — 検索流入があるページの比率。パーセントではなく比率（0.8235 = 82.35%）。
        - `averageEstimatedTrafficPerPage` number, required — 1ページ平均の推定流入数
        - `averageRankingKeywordCountPerPage` number, required — 1ページ平均のランクインキーワード数
        - `averageTrafficValuePerPage` number, required — 1ページ平均の集客価値（USD）
      - `histories` object[], required — 推移データ（0〜100指数・小数第2位・12点）。常に返却される。
        - `date` string, required — 各月末日（YYYY-MM-DD）。取得済み履歴中の最新月末を末尾に11ヶ月前までの12点。
        - `etvIndex` number, required — 推定流入数の推移指数（0〜100・小数第2位）。系列内最大月を100とする比例スケール。
        - `keywordCountIndex` number, required — 獲得キーワード数の推移指数（0〜100・小数第2位）。系列内最大月を100とする比例スケール。
        - `pageCountIndex` number, required — ページ数の推移指数（0〜100・小数第2位）。系列内最大月を100とする比例スケール。
      - `distributions` object, required — ランク帯・流入数帯の分布
        - `rankingPosition` object, required — キーワードの検索順位分布（整形ラベル別の生の件数）。
          - `1-3` number, required
          - `4-10` number, required
          - `11-20` number, required
          - `21-50` number, required
          - `51-100` number, required
          - `1-10` number, required
          - `1-20` number, required
          - `1-30` number, required
        - `pageTraffic` object, required — ページの推定流入数分布（整形ラベル別の生の件数）。
          - `0` number, required
          - `10001+` number, required
          - `1001-10000` number, required
          - `101-1000` number, required
          - `1-100` number, required
          - `1000+` number, required
          - `100+` number, required
          - `1+` number, required
  - `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)