# ツールリファレンス

Kafkai MCPサーバーが提供する全ツールを、役割ごとに説明します。ツール名はそのまま識別子です。エージェントからも、この名前で参照します。

ツールを1つずつ読む前に全体の使い方を知るには、[プロンプト例](https://kafkai.com/ja/prompts/)から始めてください。例ごとに、エージェントが裏で呼び出すツールを示しています。

## 他のSEOツールを使ったことがある場合

同じ機能でも、SEOツールによって呼び方が異なります。以下は、他のSEOツールでの名称とKafkaiのツール名の対応表です。

| 他のSEOツールでの呼び方 | Kafkaiのツール |
|---|---|
| コンテンツギャップ分析 | `kafkai_get_catchup_keywords` |
| キーワード調査、キーワード候補 | `kafkai_get_complement_keywords` |
| トピッククラスタリング | `kafkai_get_keyword_clusters` |
| 競合調査 | `kafkai_find_competitors` |
| 被リンクプロフィール | `kafkai_get_backlinks` |
| リンクインターセクト、被リンクギャップ | `kafkai_get_link_gaps` |
| 順位追跡（日次ではなく、ツール呼び出し時） | `kafkai_get_ranking_changes` |
| 検索結果の確認 | `kafkai_check_search_results` |
| マーケットプレイスの順位確認（Amazon、Googleショッピング） | `kafkai_check_marketplace_results` |

## 共通仕様

- **応答形式**：すべてのツールがJSONを返します。成功した応答には `next_step_suggestion` が含まれます。次に呼び出すツールや、Webで検索すべき語を、サーバー側で判断した内容です。エージェントは特別なプロンプトなしで、この提案に従います。
- **料金**：各ツールの説明に料金を記載しています。エージェントは、呼び出す前に無料か有料かを判断できます。無料のツールには「無料」と記載しています。料金の一覧は[クレジットと料金](https://kafkai.com/ja/docs/credits/)に掲載しています。
- **利用明細**：課金対象のツールは、応答の末尾に `_usage` オブジェクトを付けます。呼び出しの費用と残高を示します。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。
- **件数の上限**：`limit` 引数には、サーバー側の上限があります。キーワードの一覧は100件、クラスターは50件です。上限を超える値を指定してもエラーにはならず、上限までの件数を返します。上限を超える一覧は、1ページずつ読み取ります。詳しくは後述の[長い一覧を読み取る](#長い一覧を読み取る)をご覧ください。
- **識別子**：プロジェクトは `project_id`、競合サイトは `competitor_domain`、公開先は `destination_id` で指定します。いずれも、対応する一覧ツールが返す値です。

## 長い一覧を読み取る

調査で得られるキーワードは、1回の呼び出しで返しきれない件数になることがあります。そのため一覧系のツールは、1ページずつ返します。ページを返す応答には、そのページの位置を示す3つの項目が入ります。

- `count`：この応答に含まれる件数
- `total_matching`：ページの取得元となった一覧全体の件数
- `offset`：このページに到達するまでに読み飛ばした件数

次のページを読み取るには、`offset` に `limit` の値を加えて、同じツールを再度呼び出します。続きがある間は、`next_step_suggestion` が次に指定すべき `offset` を示します。エージェントは、手順を指示されなくても一覧をたどれます。`count` が `limit` より小さい場合、そのページが最後です。一覧の末尾を超える `offset` を指定した場合、Kafkaiはエラーを返さず、件数がいくつあるかを示します。

`offset` を受け付けるツールは決まっています。キーワード、クラスター、被リンク、Search Console、Bing Webmaster Tools、アクセス解析の一覧ツールです。プロジェクト、競合サイト、公開先のように短い一覧を返すツールは受け付けません。

ページごとに1回の呼び出しとなり、そのたびに呼び出し料金がかかります。したがって、100件を1回で読み取るほうが、20件を5回に分けて読み取るより安くなります。長い一覧が必要な場合は、ツールが許す範囲でページを大きく指定し、必要なデータが揃った時点で読み取りを終えます。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。

## プロジェクトと競合サイト

### kafkai_list_projects

プロジェクトの一覧を返します。プロジェクトID、サイトURL、状態、対象地域、キーワード数、競合サイト数が含まれます。多くのツールが `project_id` を必要とするため、通常はこのツールを最初に呼び出します。各プロジェクトには `setup_reminders` も入ります（[設定のリマインダー](#設定のリマインダー)を参照）。無料です。

引数：なし

### kafkai_get_project_summary

プロジェクトの全体像を返します。サイト情報、ニッチ（専門領域）、対象地域、4C戦略と掲載順位ごとのキーワード数、競合サイトの一覧です。加えて、データの有無を示すブロックが入ります。`authority` は、対象サイトの強さを各競合サイトと並べたものです。`backlinks` は、対象サイトと各競合サイトに被リンクデータがあるかどうかと、プロファイル全体の件数です。どの被リンクツールを呼び出すべきかは、このブロックの `next_step_suggestion` が示します。`search_console` は、対象サイトのGoogle Search Consoleプロパティを読み取れるかどうか、ドメインの認証状況（`domain_verified`）、データの対象期間です。読み取れる場合は、`next_step_suggestion` が2つのSearch Consoleツールを示します。読み取れない場合は、足りない手順（ドメイン認証、または権限の付与）を示します。`bing_webmaster` は、Bing Webmaster Toolsについて同じ内容を、データの対象となる週とあわせて示します。`marketplaces` は、プロジェクトが利用したマーケットプレイスごとに、登録済みの識別情報、確認したキーワードの数、直近の確認日時を示します。識別情報を登録するか、`kafkai_check_marketplace_results` を呼び出すまでは、空のリストです。応答には `recommended_strategy` も含まれます。機会のもっとも多い戦略を、理由とあわせて示します。`last_research` は、プロジェクトの直近の調査実行です。全体更新と、競合サイト追加時の調査が対象です。実行中は `pending` を示します。完了後は結果（`success`、`partial`、`failed`）を示し、失敗があればその理由も示します。`setup_reminders` は、まだ完了していない設定手順です（[設定のリマインダー](#設定のリマインダー)を参照）。無料です。

`site_metadata` は、Kafkaiが最後に読み取った対象サイトのホームページの要約です。ページ全体は含みません。次の項目が入ります。

- `url`、`code`：Kafkaiが読み取ったURLと応答コード
- `page_title`、`description`：ページのタイトルとメタディスクリプション
- `headings`：H1からH3までの見出しのテキスト（先頭から最大20件）
- `excerpt`：ページ本文の先頭1,000文字
- `fetched_at`：Kafkaiがページを読み取った日時（UTC）

Kafkaiは、プロジェクトの作成時と、`kafkai_update_keywords` の開始時にホームページを読み取ります。直近の読み取りに失敗した場合、Kafkaiは前回のページを残し、`fetch_error` と `fetch_error_at` を加えます。この場合、要約は古い可能性があります。ページを一度も読み取れていない場合は、競合サイト追加時の調査でも読み取りを試みます。Kafkaiが日時の記録を始める前に作成したプロジェクトには、次回の更新まで `fetched_at` がありません。

引数：

- `project_id`：対象のプロジェクト

### kafkai_list_competitors

プロジェクトに登録した競合サイトの一覧を返します。各競合のキーワード数と、調査の `status` が含まれます。調査に失敗した競合は `failed` と表示され、理由は `error` に入ります。その競合のキーワード一覧は不完全です。再試行の方法は、応答の `next_step_suggestion` が示します。`kafkai_update_keywords` なら、すべてのドメインを調査し直します。競合サイトを削除して追加し直すなら、競合料金1件分で済みます。キーワード数がもっとも多い `top_competitor` と、直近の調査実行 `last_research` も返します。無料です。

引数：

- `project_id`

### kafkai_find_competitors

プロジェクトの対象サイトが検索で競合しているサイトを見つけます。根拠は、対象サイトが実際に順位を持つキーワードです。ホームページの内容からの推測ではありません。Kafkaiは、プロジェクトの国で同じキーワードに順位を持つドメインを集め（トラフィック上位1,000サイトは除外）、双方のキーワード群がどれだけ重なるかで採点します。そのうえで、4Cのツールと同じ勝算（winnability）の基準で対象サイトと比べ、各サイトの種類を判定します。無関係なドメインは除きます。プロジェクトに登録済みの競合サイトには `already_tracked` が付くため、一覧は「ほかにどのサイトがあるか」として読めます。

応答には、2つの一覧が含まれます。

- `competitors`：対象サイトと競合するサイト
- `comparison_sites`：レビューサイト、比較サイト、ディレクトリ、まとめ記事のメディア。競合サイトではないため、Kafkaiは `competitors` に含めず、別の一覧で返します。アフィリエイトサイトや比較サイト経由で集客している場合は、この一覧が監視の対象です

どちらの一覧も、各行には次の値が含まれます。

- `domain`、`relationship`（`direct`、`adjacent`。判定できなかった場合は `unknown`。`comparison_sites` では常に `aggregator`）
- `winnability`、`rank`（0〜1000）
- `intersections`（共有するキーワード数）、`overlap`（その数を双方のキーワード群に対する割合にした値。0〜1）
- `avg_position`、`etv`、`keywords_count`、`sample_keywords`、`already_tracked`

`filtered_out` は、Kafkaiが除いたドメインの数を理由ごとに示します。`unrelated` は無関係なサイト、`unreachable` はドメインまたはホスト名が解決できなくなったサイトです。キーワードデータには、閉鎖したサイトがしばらく残ります。そのためKafkaiは、候補のドメイン名を1件ずつDNSで解決し、解決できない候補を除きます。`site` は、対象サイト自身のキーワード数、推定トラフィック、ランクです。競合サイトの行の順序は、直接の競合（`direct`）が先です。その中では、勝算のあるサイトが巨大なサイトより先で、次に `overlap` の大きい順です。比較サイトの行は、`overlap` の大きい順です。

行を読むときは、次の3点に注意します。

- Googleがまだ1つのキーワードにも順位を付けていないサイトは、顧客が行う検索から答えます（`method` が `customer_searches` になり、`seed_keywords` にその検索語が入ります）。それらの検索で1ページ目に出るサイトを、小さいサイトから順に返します。この経路では `overlap`、`etv`、`keywords_count` は空になり、`winnability` は `unknown` です。
- Kafkaiが返すのは候補と根拠です。どれを重視するかの判断は、エージェント側で行います。競合サイトの登録は、別の有料ステップである `kafkai_add_competitor` で行います。
- 比較サイトを継続して追う場合は、`kafkai_add_competitor` で登録します。Kafkaiは、ほかの競合サイトと同じようにキーワードと順位を追跡します。あるキーワードの1ページ目にどの比較サイトが出ているかは、`kafkai_check_search_results` で確認します。

料金は、このツール専用の呼び出し料金です。一覧系の参照ツールより高くなります。プロジェクトが持つデータを読むのではなく、競合候補、サイトの強さ、判定のデータを新たに取得するためです。行単位の従量分はほかの参照ツールと同じで、数えるのは `competitors` の行だけです。`comparison_sites` の行には課金しません。結果は1日キャッシュするため、同じ条件で呼び出すと同じ一覧を返します。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。

引数：

- `project_id`
- `limit`：返す競合サイトの最大数（既定10、最大20）。`comparison_sites` も同じ数までです

### kafkai_get_competitor_analysis

競合サイト1件を詳細に分析します。ブランドの説明、競合だけが上位表示されているキーワード（キャッチアップ）、双方が上位表示されているキーワード（競合）を返します。一覧系のツールより基本料金が高くなります。

各キーワードには、前回の計測からの競合の変化として `competitor_previous_rank` と `competitor_rank_change` が入ります。また、Competeの行には、対象サイト側の `our_previous_rank` と `our_rank_change` も入ります。

引数：

- `project_id`
- `competitor_domain`：`kafkai_list_competitors` が返す値
- `include_history`：各キーワードに順位の推移を含める場合に指定。競合の順位は `competitor_history` に、対象サイトも上位表示されている場合は `our_history` に入ります

## キーワード調査（4C戦略）

4つの戦略ツールは、同じ形式のデータを返します。各キーワードには、検索ボリューム、キーワード難易度、CPC、順位、上位ページのタイトルと説明文（該当する場合）、タグ、データの取得時期（`first_seen` と `last_updated`）が含まれます。`recommended` には、ボリュームと難易度から見て着手しやすいキーワードが入ります。

順位には、すべて計測日時が付きます。各キーワードには、前回の計測からの各サイトの変化も含まれます。

- 対象サイトが上位表示されている場合：`our_previous_rank` と `our_rank_change`
- 競合が上位表示されている場合：`competitor_previous_rank` と `competitor_rank_change`

変化が正の値なら、順位が上がったことを示します。Catch-up、Consolidate、Competeでは、`include_history` も指定できます。指定すると、各キーワードに順位の推移が古い順で付きます。上位表示されている各サイトについて、Kafkaiが記録してきた値です（`our_history` と `competitor_history`）。順位が変わらなかった時点は除かれます。「直近3か月で何が動いたか」を知るには、後述の `kafkai_get_ranking_changes` を使います。

Catch-up、Consolidate、Competeの3つは、対象サイトと競合を比較します。競合を1件も登録していない間は、結果が空になります。一方のComplementは比較しないため、競合の有無にかかわらず使えます。競合を登録せずに掲載順位を確認するには、後述の `kafkai_get_ranked_keywords` を使います。

4つとも、引数は共通です。

- `project_id`
- `limit`：返す最大件数（既定20、最大100）
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の `next_step_suggestion` に次の値が入ります。全体の件数は `total_matching` が示します
- `include_history`：Catch-up、Consolidate、Competeのみ。上位表示されている各サイトの順位の推移を含める場合に指定

### kafkai_get_catchup_keywords

Catch-up（キャッチアップ）。競合が上位表示され、対象サイトが上位表示されていないキーワードです。コンテンツが不足している領域を示します。どの競合が、どのタイトルで上位表示されているかまでわかるため、エージェントは対象ページを特定したうえで調査に進めます。

### kafkai_get_consolidate_keywords

Consolidate（強化）。対象サイトが上位表示され、競合が上位表示されていないキーワードです。すでに成果の出ている領域であり、内容を強化する価値があります。

### kafkai_get_compete_keywords

Compete（競合）。対象サイトと競合の双方が上位表示されているキーワードです。双方の順位を返すため、順位差の小さいキーワードから優先的に改善できます。

### kafkai_get_complement_keywords

Complement（補完）。対象サイトも競合も、まだ対応していない関連キーワードです。今後追加すべきテーマの候補を示します。複数のテーマから同じキーワードが提案された場合も、返すのは1件だけです。`limit`は、重複を除いたキーワードの件数になります。

### kafkai_get_keyword_clusters

意味的に近いキーワードをまとめたクラスターを返します。1本の記事でまとめて狙えるグループです。各クラスターには、平均検索ボリューム、平均難易度、平均CPC、所属キーワードが含まれます。応答では、ボリュームのもっとも大きいクラスターを推奨します。

引数：

- `project_id`
- `limit`：返す最大クラスター数（既定10、最大50）
- `offset`：読み飛ばすクラスター数。ページ送りに使います（既定0）。続きがある間は、応答の `next_step_suggestion` に次の値が入ります。全体の件数は `total_matching` が示します

## 対象サイトの掲載順位

### kafkai_get_ranked_keywords

対象サイトがすでに上位表示されているキーワードと、その順位の変化を返します。これは4C戦略ではありません。4C戦略は競合との比較ですが、このツールは対象サイト自身の順位を直接読み取ります。競合を1件も登録していないプロジェクトでも使えるため、作成直後のプロジェクトで最初に役立ちます。

各キーワードには、現在の順位、前回の順位、前回の計測からの変化、新規に順位がついたかどうかに加えて、検索ボリューム、難易度、CPC、上位表示されているページが含まれます。`progress` には、上昇・下降・変化なし・新規の件数と、3位以内および10位以内の件数が入ります。

`include_history` を指定すると、各キーワードにKafkaiが記録してきた順位の推移が、古い順で付きます。推移をグラフにするのに十分な情報です。順位が変わらなかった時点は除かれるため、更新1回につき1点ではなく、変化した時点だけが並びます。

数値を読むときは、次の3点に注意します。

- ここに出るキーワードは、ConsolidateやCompeteにも出ることがあります。切り出した一部ではなく、掲載順位の全体像です。
- `progress` が数えるのは、その呼び出しが返したキーワードだけです。プロジェクト全体の件数は `total_ranked_keywords` です。
- 作成直後のプロジェクトには、比較対象となる前回の計測がありません。この場合の変化は、最初に確認した順位からの差です。

`kafkai_update_keywords` を実行すると、順位が更新されます。各キーワードの推移に次の1点が加わるのも、このときです。

引数：

- `project_id`
- `limit`：返す最大件数（既定20、最大100）
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の `next_step_suggestion` に次の値が入ります。全体の件数は `total_matching` が示します
- `include_history`：各キーワードの順位の推移を含める場合に指定

## 順位の変化

### kafkai_get_ranking_changes

一定期間に順位が上がった、または下がったキーワードを返します。対象サイト、競合サイト1件、すべての競合サイトのいずれかを指定できます。Kafkaiが計測する順位には、すべて計測日時が付きます。そのため、各キーワードについて期間開始時点の順位と現在の順位を比較できます。結果は、変化の大きい順に並びます。次のような質問に答えるツールです。

- 直近3か月で何が動いたか
- この競合はどこで順位を落としているか
- 失ったキーワードはどれか
- 競合の順位下落から狙えるキーワードはどれか

各キーワードには `movement` が入ります。値は次の4種類です。

- `improved`：上昇
- `declined`：下降
- `new`：現在は上位表示されているが、期間開始時点ではされていなかった
- `lost`：期間開始時点では上位表示されていたが、現在はされていない

あわせて、次の値が含まれます。

- `current_rank` と `measured_at`：現在の順位と、その計測日時
- `baseline_rank` と `baseline_measured_at`：期間開始時点の順位と、その計測日時
- `rank_change`：変化量。正の値なら上昇
- `first_seen`：初回確認日
- 検索ボリューム、難易度、CPC、上位表示されているページ
- `source`：順位の出どころ。`measured` はKafkaiが計測した順位。`search_console` は、計測値がなかったときにKafkaiがSearch Consoleの検索クエリから登録した行で、サイトURLに対する28日間の平均掲載順位、ボリュームは表示回数、難易度は0です。両者を互いに比較することはありません。Search Consoleの行が後で計測値に置き換わった場合は、`lost` にはせず一覧から外します

競合を指定した場合は、`competitor_domain`、`our_rank`、`our_rank_source` も付きます。`our_rank` は、同じキーワードで対象サイトが現在どの順位にいるかです。Kafkaiは計測した順位があればそれを使います。計測値がない場合はSearch Consoleの平均掲載順位を使い、`our_rank_source` は `search_console` になります。競合が順位を落としたキーワードのうち、対象サイトがすぐ後ろにいるもの、またはまだ上位表示されていないものは、記事を書く好機です。

`summary` には、そのサイトで計測したすべてのキーワードの件数が入ります。上昇・下降・変化なし・新規・消失の5つに分けた数です。返したキーワードだけの集計ではありません。変化のなかったキーワードは件数にだけ数え、一覧には含めません。

数値を読むときは、次の3点に注意します。

- 更新は指示したときだけ実行されるため、「ちょうど90日前」の計測はありません。比較の基準は、期間開始時点以前の最新の計測です。その計測日時が `baseline_measured_at` です。
- 期間の途中で計測が始まった場合（`period.tracked_since`）は、最初の計測を期間開始時点の代わりにします。その初回計測に含まれていたキーワードは、新規とはみなしません。
- 同じキーワードの行は1つにまとめます。戦略の間を移動したキーワードも、推移は1本につながります。

`kafkai_update_keywords` を実行すると、順位が更新されます。計測日時付きの次の1点が加わるのも、このときです。

引数：

- `project_id`
- `competitor_domain`：空なら対象サイトを対象にします。競合のドメイン（`kafkai_list_competitors` が返す値）なら、その競合です。`all` なら、すべての競合をまとめて1つの一覧にします。このとき、応答に `competitor_domains` と `by_competitor` の内訳が加わります
- `days`：期間の日数（既定90、最大365）
- `movement`：`all`（既定。変化なし以外のすべて）、`improved`、`declined`、`new`、`lost` のいずれか
- `limit`：返す最大件数（既定20、最大100）
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。`total_matching` は `movement` に一致する件数です。`summary` は引き続きサイト全体を数えます

## 被リンク

対象サイトと各競合サイトに、どのサイトからリンクが張られているか、リンク元サイトの強さ、各リンクを最後に確認した日時、サイトごとに獲得・喪失したリンク数の推移を返します。Kafkaiが返すのはデータです。リンク元サイトに共通するテーマや、失われたリンクのうち狙う価値があるものの判断は、エージェント側で行います。

Kafkaiは、被リンクをキーワード調査の一部として取得します。プロジェクトの作成時は対象サイトと各競合サイト、競合サイトの追加時はその競合、`kafkai_update_keywords` の実行時はすべてのサイトが対象です。以下の3つの参照ツールは、そのスナップショットから応答します。`kafkai_update_backlinks` は、キーワードを取得し直さずに被リンクだけを更新します。応答には取得日時（`as_of`）が付きます。未取得のサイトは、空の行を返す代わりに、未取得であることを示します。

### kafkai_get_backlinks

対象サイト、または競合サイト1件にリンクしているサイトを返します。リンク元ドメインごとに1行で、そのドメインからのもっとも強いリンクを、強い順に並べます。次のような質問に答えるツールです。

- 競合Xにリンクしているのはどのサイトか
- 対象サイトにリンクしているサイトはどれくらい強いか
- 競合Xが失ったリンクのうち、代わりに獲得できそうなものはどれか

最後の質問には、`status` に `lost` を指定します。失われたリンクの各行は、かつて `target_page` のようなページにリンクし、その後リンクをやめたサイトです。`last_seen` が、リンクを最後に確認した日時です。

各行には、次の値が含まれます。

- `referring_domain`、`referring_page`、`target_page`、`page_title`、`anchor`
- `link_type`、`dofollow`
- `link_rank`、`referring_page_rank`、`referring_domain_rank`：0〜1000のスケール。大きいほど強い
- `spam_score`、`platform_types`、`country`
- `first_seen`、`last_seen`、`is_lost`、`is_new`、`is_broken`、`links_from_domain`

数値を読むときは、次の2点に注意します。

- `profile` には、リンクプロファイル全体の値が入ります。`domain_rank`、`backlinks_total`、`referring_domains_total`、nofollowと切れたリンクの件数、リンク種別・プラットフォーム・国・TLDの内訳です。プロファイルの規模は、この合計値で示します。
- 行は、その一部の標本です。Kafkaiが保存するのは、最大1,000件のリンク元ドメインからのもっとも強いリンクと、直近1年で失われたリンクのうち強いものです。`coverage` に、保存した行数と、稼働中リンクの標本が全件かどうかが入ります。「18,452件のうち上位1,000件」のように、全件を見たかのような表現を避けて答えられます。

引数：

- `project_id`
- `competitor_domain`：空なら対象サイト。競合のドメイン（`kafkai_list_competitors` が返す値）なら、その競合。1回の呼び出しで1サイト
- `status`：`live`（既定）、`lost`（直近1年で失われたリンク）、`all` のいずれか
- `limit`：返す最大件数（既定20、最大100）
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の `next_step_suggestion` に次の値が入ります

### kafkai_get_backlink_changes

一定期間に、サイトが獲得・喪失した被リンク数とリンク元ドメイン数を返します。対象サイト、競合サイト1件、またはプロジェクト内の全サイトを並べて指定できます。Kafkaiはサイトごとに、日次の獲得・喪失件数を保持しています（初回取得時から1年分）。期間の値はその合計で、月ごとの内訳も付きます。次のような質問に答えるツールです。

- 競合Xは直近3か月で何件のリンクを獲得したか
- 競合のリンク獲得は加速しているか
- 対象サイトは競合に遅れを取っていないか

サイトごとの行には、次の値が含まれます。

- `status` と `as_of`
- `totals_now`：`backlinks`、`referring_domains`、`domain_rank`
- `totals_previous`：前回取得時の同じ合計値。取得日時 `as_of` 付き
- `totals_check`：前回と今回の合計値の差を、その間の日次件数と照合した結果
- `period_totals`：`new_backlinks`、`lost_backlinks`、`net_backlinks`、`new_referring_domains`、`lost_referring_domains`、`net_referring_domains`
- `by_month`：月ごとの内訳
- `data_from` と `data_to`：保存している履歴が実際に対象とする日付の範囲

`status` が `ready` でないサイトには、まだ件数がありません。

合計値は、取得日時点でのリンク索引の大きさです。索引は再構築されることがあります。スパムネットワークの除外や再集計がその例です。そのため、2つの合計値の差は、獲得・喪失したリンク数ではありません。獲得・喪失は日次件数で読みます。再構築では、片方の合計値だけが動くこともあります。そのため `totals_check` は、`referring_domains` と `backlinks` をそれぞれ照合します。各項目には、`totals_previous` から `totals_now` への変化、2回の取得の間の日次件数、その差が入ります（`change`、`net_from_daily_counts`、`unexplained`、`consistent`）。どちらかが食い違うと、最上位の `consistent` は `false` になり、`note` にどの合計値かが入ります。合計値が欠けているときや、前回の取得がKafkaiの保存する日次件数より古いときは照合できないため、その項目の `consistent` は `null` になります。両方とも照合できないときは、最上位の `consistent` も `null` になります。合計値は取得日時とともに引用し、獲得・喪失は `period_totals` で読みます。

引数：

- `project_id`
- `competitor_domain`：空なら対象サイト。競合のドメイン（`kafkai_list_competitors` が返す値）なら、その競合。`all` なら、対象サイトとすべての競合を1サイト1行で返します
- `days`：期間の日数（既定90、最大365）

### kafkai_get_link_gaps

競合サイトの2つ以上にリンクしていて、対象サイトにはリンクしていないサイトを返します。いわゆるリンクギャップです。リンク元ドメインごとに1行で、強い順に並びます。各行には、各競合サイトに張られているリンクが`links` として付きます。複数の競合サイトにすでにリンクしているサイトは、同じテーマを扱い、同種のサイトへのリンクを受け入れています。そのため、最初にリンクを依頼する候補になります。Kafkaiが返すのは行データです。どのサイトに依頼するか、何を提供するかの判断は、エージェント側で行います。

各行には、次の値が含まれます。

- `referring_domain`、`competitor_count`
- `referring_domain_rank`（0〜1000。大きいほど強い）、`spam_score`、`country`
- `links`：競合サイトごとのリンク（`referring_page`、`target_page`、`anchor`、`dofollow`、`link_rank`、`last_seen`）

応答が対象とした競合サイトは `competitors_with_data` に入ります。まだデータのない競合サイトは `competitors_without_data` に入ります。

行を読むときは、次の2点に注意します。

- 対象サイトの被リンクデータが必要です。「対象サイトにリンクしていない」は、そのデータで判定するためです。競合サイトのデータも、`min_competitors` 件以上必要です。そろうまでは、不足しているサイトと取得方法を応答で示します。
- 「対象サイトにリンクしていない」は、保存している対象サイトの稼働中リンクの標本（`own_site_coverage`。上記の `coverage` と同じ形式）で判定します。標本の外にあるサイトは、対象サイトにリンクしていても一覧に現れることがあります。

引数：

- `project_id`
- `min_competitors`：ギャップとみなす条件となる、リンク先の競合サイト数（既定2、最小1）。`1` を渡すと、いずれかの競合サイトにリンクしていて対象サイトにはリンクしていないサイトをすべて返します
- `limit`：返す最大件数（既定20、最大100）
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。続きがある間は、応答の `next_step_suggestion` に次の値が入ります

### kafkai_update_backlinks

プロジェクトの対象サイトとすべての競合サイトについて、被リンクデータを取得し直します。リンク元サイトとその強さ、直近1年で失われたリンクと最後に確認した日時、1年分の日次の獲得・喪失件数が対象です。上記3つの参照ツールは、このデータから応答します。

被リンクは、`kafkai_create_project`、`kafkai_add_competitor`、`kafkai_update_keywords` の実行時にも取得します。このツールは、キーワードを取得し直さずに被リンクだけを更新するためのものです。被リンク機能より前に作成したプロジェクト、取得に失敗したあと、1日前のスナップショットでは古すぎる場合に使います。

取得はバックグラウンドで実行し、サイト1件につき1分ほどかかります。直近1日以内に取得したサイトは飛ばします。取得中のサイトを二重に取得することもありません。そのため、続けて2回呼び出しても追加の費用はかかりません。応答には、今回取得するサイト（`domains`）、飛ばしたサイト（`skipped_fresh`）、取得中のサイト（`in_flight`）が入ります。

料金は、実際に取得したサイト1件ごとに、被リンクのみの料金がかかります。キーワードは取得しないため、全体更新より安くなります。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。

引数：

- `project_id`

## ドメイン認証

Kafkaiは、対象サイトの非公開データを、そのドメインを管理していると認証できたアカウントにだけ返します。現在はSearch Console、Bing Webmaster Tools、アナリティクス、Googleアナリティクスのデータが対象です。今後も他のデータソースを同じ仕組みで扱います。

証明に使うのは、アカウントとドメインの組み合わせごとに固有のコード1つです。コードの設置方法は2つあり、どちらでも認証できます。

- **DNSのTXTレコード**：プロジェクトの登録ドメイン（最上位のドメイン）に追加します。追加するドメインは、プロジェクトのホストから登録ドメインを求めて決めます。たとえば `blog.hogehoge.jp` のプロジェクトでは `hogehoge.jp` に、`example.co.jp` のプロジェクトでは `example.co.jp` に追加します（「登録ドメイン」の判定はPublic Suffix Listで行うため、`example.co.jp` のような2段階の国別サフィックスはそのまま残ります）。1つのレコードで、同じアカウントのすべてのサブドメインプロジェクトに対応できます。
- **HTMLのメタタグ**：DNSを編集できないサイト向けの方法です。ページの `<head>` に `<meta name="kafkai-verification" content="…">` を追加します。タグはドメインそのもののページに置きます。サブドメインのページでは認証できません。共有サーバーでは、各利用者が自分のサブドメインは編集できても、ドメインそのものは管理していないためです。ホスティングサービスのサブドメイン（`alice.blogspot.com` など）は、それ自体が登録ドメインなので、自分のタグで認証できます。

1つのドメインを、2つのアカウント（サイトの所有者と代理店など）がそれぞれ認証することもできます。その場合は、それぞれのコードを使います。どちらのツールも無料です。

1. `project_id` を指定して、`kafkai_verify_domain` を呼び出します。応答には、追加するものが2つ入ります。`dns_record`（`type` は `TXT`、`name` はドメイン、`value` は `kafkai-verification=` に続くコード）と、`meta_tag`（貼り付ける `<meta>` タグそのもの）です。設置しやすいほうを使います。
2. 選んだほうを設置します。TXTレコードはドメインのDNSプロバイダーで追加し、メタタグはドメインそのもののページの `<head>` に追加します。
3. `kafkai_check_domain_verification` を呼び出します。KafkaiはまずTXTレコードを照会し、見つからない場合はドメインのページでメタタグを探します。どちらかが見つかれば、`status` が `verified` になります。DNSの変更は通常数分で反映されますが、最大48時間かかることがあります。見つからない場合は、時間をおいて呼び出し直します。

Kafkaiは、認証済みのドメインを定期的に再照会します。レコードやタグを削除すると、元に戻すまでデータを返しません。コードは変わらないため、やり直すのはレコードかタグの追加だけです。

同じレコード、メタタグ、確認ボタン、認証状況は、アカウントの[ドメインページ](https://kafkai.com/ja/accounts/domains/)にもあります。ドメインごとに1件ずつ表示します。エージェントを介さずにブラウザーからコピーする場合は、このページを使います。どちらの方法でも、ドメインごとのコードは共通です。

### kafkai_verify_domain

プロジェクトのドメイン認証を開始し、追加するTXTレコードとメタタグを返します。認証を開始済みの場合は、同じコードを返します。何度呼び出しても、コードは変わりません。

引数：

- `project_id`

応答には、`domain`（レコードを追加する登録ドメイン）、`status`（`pending` または `verified`）、`dns_record`（`type`、`name`、`value`）、`meta_tag`（貼り付ける `<meta>` タグ）、`verified_at`、`last_checked`、`last_error`、`next_step_suggestion` が入ります。

### kafkai_check_domain_verification

レコードを照会し、見つからない場合はメタタグを探して、`kafkai_verify_domain` と同じ形式で結果を返します。どちらも見つからない場合、`status` は `pending` のままです。探した内容は `last_error` に入ります。照会に応答がなかった場合（タイムアウト）は、何も変わりません。数分後にもう一度呼び出します。`kafkai_verify_domain` より先に呼び出しても問題ありません。コードを作成し、追加するTXTレコードとメタタグを応答に含めます。

引数：

- `project_id`

## Search Console

対象サイトのGoogle Search Consoleのデータを、2つのツールで読み取り、3つ目の無料のツールで更新します。順位データが検索結果の標本であるのに対し、こちらはGoogleが対象サイトについて実際に記録した内容です。表示されたすべての検索クエリについて、実際のクリック数、表示回数、クリック率、平均掲載順位がわかります。順位データだけでは答えられない問いに答えます。「何が検索されたか」「どのページがクリックされたか」「何が変わったか」の3つです。

2つのツールは、同じ期間を扱います。保存している最新の28日間と、その直前の28日間を比べます。各行と、プロパティ全体の `totals` には、直前の期間との差として `clicks_change`、`impressions_change`、`position_change` が付きます。順位が上がったときは、`position_change` が正の値です。順位ツールと同じ符号です。

データを返すまでに、2つの手順があります。`search_console.status` が `not_connected` の間は、どちらのツールも、足りない手順を `next_step_suggestion` で示します。エージェントは、その手順をそのまま案内できます。

1. ドメインを認証します。手順は、上の「ドメイン認証」のとおりです。認証前は、Kafkaiはそのドメインについて何も返しません。プロパティがあるかどうかも返しません。
2. Kafkaiにプロパティの読み取り権限を付与します。Search Console上で1回だけ行い、共有するのはメールアドレス1つだけです。[Google Search Console](https://search.google.com/search-console)でプロパティを開き、**設定** > **ユーザーと権限** > **ユーザーを追加** を開いて、Kafkaiの読み取り用アドレスを入力し、権限に **制限付き** を選びます。読み取り用アドレスは、ドメイン認証後に `next_step_suggestion` に入ります。スクリーンショット付きの手順は、[Google Search Consoleを連携する](https://kafkai.com/ja/docs/google-search-console/)をご覧ください。

次回の調査実行（`kafkai_update_keywords`）または `kafkai_update_search_console` の呼び出しのうち、先に行ったほうで、Kafkaiがプロパティを検出します。検出後は、履歴を16か月分取り込みます。最初の同期が終わるまで、ステータスは `syncing` です。以降は、調査実行のたびにデータを更新します。`kafkai_update_search_console` を使えば、Search Consoleのデータだけを無料で更新できます。

数値を読むときは、次の2点に注意します。いずれもGoogle側の仕様です。

- Googleは、匿名化したクエリを省きます。そのため、クエリ行の合計は、プロパティ全体の実数より小さくなります。`totals` は実数です。`coverage` には、クエリ行の表示回数（`visible_impressions`）、実数の合計（`total_impressions`）、その割合（`visible_impressions_share`）が入ります。割合は、その呼び出しが返した行を対象に計算します。
- Google Discoverは、ページと合計だけを報告し、クエリを報告しません。`search_type='discover'` は、pagesビューとtrendビューでだけ使えます。

### kafkai_get_search_console_data

対象サイトが表示された検索クエリ、トラフィックを集めたページ、日別の合計を返します。同じ期間を、3つのビューで見ます。

- `view='queries'`（既定）：現在の期間の検索クエリごとに1行です。`query`、`clicks`、`impressions`、`ctr`、`position` に加えて、直前の期間の値（`prior`）と3つの差分が入ります。
- `view='pages'`：対象サイトのページごとに1行です。Googleの日別ページ集計（実数）を合計した値です。
- `view='trend'`：直前の期間から現在の期間までの、新しい側から数えた1日ごとに1行です。古い順に並ぶため、トラフィックが変わった日がわかります。全期間を一度に取得するには、`limit=100` を渡します。

すべての応答に、`search_console`（`property`、`status`、`domain_verified`）、`window`、`prior_window`、`totals` が入ります。内訳として、`totals` には `current`、`prior`、差分が入ります。併せて、`kafkai_get_ranked_keywords` も使います。このツールにあって順位データにないクエリは、Kafkaiの標本が取りこぼした実際の検索です。

引数：

- `project_id`
- `view`：`queries`（既定）、`pages`、`trend` のいずれか
- `order_by`：queriesビューの並び順。`impressions`（既定）、`clicks`、`position`（上位から）のいずれか。pagesビューは常に表示回数順です
- `contains`：この文字列を含むクエリ（またはページURL）だけを返します。大文字と小文字は区別しません。trendビューには対象がないため、この引数は無視し、応答にも含めません
- `search_type`：`web`（既定）または `discover`
- `limit`：返す最大件数（既定20、最大100）。trendビューでは、新しい日から数えた日数です。`limit=100` を渡すと、全期間を一度に返します。両期間の日数は、常に `total_matching` が示します
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。trendビューでは、最新の日から数えて過去へさかのぼります。続きがある間は、応答の `next_step_suggestion` に次の値が入ります

### kafkai_get_search_console_insights

Search Consoleのデータから、Kafkaiが計算した「最初に取り組むべき点」を返します。指摘は5種類あります。いずれもクエリまたはページ1件です。根拠となる数値（`evidence`）と、同じ種類の中で順位付けするための `score` が付きます。

- `striking_distance`：1ページ目の少し下（既定では8〜20位）に表示され、表示回数が十分にあるクエリです。scoreは、5位に到達した場合に見込める追加クリック数です。
- `ctr_gap`：掲載順位から見込まれる水準を大きく下回るクリック率のクエリです。多くの場合、順位ではなくタイトルやスニペットの問題です。scoreは、失っているクリック数です。
- `cannibalisation`：対象サイトの2つ以上のページが表示回数を分け合っているクエリです。scoreは、対象となる表示回数です。
- `new_query`：直前の期間にはなく、現在の期間で新たに表示されたクエリです。scoreは表示回数です。
- `decay`：直前の期間と比べて、クリック数が大きく落ちたページです。Web検索とGoogle Discoverを別々に計算します。scoreは、失ったクリック数です。

応答の `definitions` には、各ルールと適用中のしきい値が入ります。種類ごとの件数は `counts` です。同じ種類の中でだけ、scoreを比較します。種類が違えば、単位も違います。指摘を計算するのはKafkaiです。何を変えるかは、`evidence` を読んだエージェントが判断します。周辺の行は、`kafkai_get_search_console_data` で確認できます。

引数：

- `project_id`
- `insight_type`：`all`（既定）、または `striking_distance`、`ctr_gap`、`cannibalisation`、`new_query`、`decay` のいずれか。`all` の場合、`limit` と `offset` は種類ごとに適用します
- `limit`：種類ごとに返す最大件数（既定20、最大100）
- `offset`：種類ごとに読み飛ばす件数。ページ送りに使います（既定0）

### kafkai_update_search_console

対象サイトのSearch Consoleの最新データを、調査実行なしで取得します。無料です。

Search Consoleのデータは、調査実行のたびに、その終わりに取得します。このツールは、キーワードと被リンクのデータを買い直さずに、Search Consoleの数値だけを新しくしたいときに使います。たとえば、保存している期間が数日前のものになっているときです。Kafkaiに読み取り権限を付与した直後のプロパティも、このツールで検出します。接続のために調査実行は必要ありません。

取得はバックグラウンドで行います。更新は約1分で終わります。プロパティの最初の取得では履歴を16か月分取り込むため、数分かかります。

GoogleはSearch Consoleのデータを1日1回、約2日遅れで公開します。そのため、Kafkaiが1つのプロパティを取得するのは1日1回までです。24時間以内の2回目の呼び出しでは何も取得せず、次に取得できる時刻を応答で示します。調査実行も、その日の取得として数えます。

先に、上の2つの手順（ドメイン認証と、読み取り権限の付与）が必要です。足りない手順があれば、応答の `next_step_suggestion` が示します。

応答には次の項目が入ります。

- `queued`：取得を開始した場合は `true`、何も取得しなかった場合は `false`
- `search_console`：`property`、`status`、`domain_verified`。読み取りツールと同じブロックです
- `next_sync_available`：次に取得を開始できる時刻
- `next_step_suggestion`：次に呼び出すツール。通常は、取得の完了後に `kafkai_get_search_console_data` を示します

引数：

- `project_id`

## Bing Webmaster Tools

対象サイトのBing Webmaster Toolsのデータを、2つのツールで読み取り、3つ目の無料のツールで更新します。Search Consoleのツールと対になるツールです。Bingは日本で2番目に使われている検索エンジンで、Googleとは別のデータツールを持っています。Bingの合計には、Copilotのチャットで対象サイトが表示された回数も含まれます。Copilotのチャット経由の表示回数は、ほかのツールでは確認できません。

データはGoogleより粗いため、ツールはその違いを明示します。

- Bingは、上位のクエリとページを**週ごと**に報告します。2つの読み取りツールが扱う期間は、保存している最新の週と、その前の週です。すべての応答に `granularity: "week"` が入ります。Kafkaiは週ごとの行を足し合わせて、より長い期間の合計を作ることはありません。
- Bingは、上位のクエリとページだけを保持します。しきい値は公開されていないため、行を合計してもサイト全体の実数には届かず、どれだけ足りないかもわかりません。`coverage` は常に `null` で、理由は `coverage_note` に入ります。`totals` は実数です。KafkaiはBingの日別の数値から合計します。日別の数値は、Copilotのチャットを含め、Bingで表示されたすべてを対象にしていて、掲載順位は含みません。
- クエリとページの各行には、掲載順位が2つ入ります。`position` は表示の平均順位で、指摘の計算に使います。`click_position` はクリックの平均順位です。

データを返すまでに、Search Consoleと同じ2つの手順があります。`bing_webmaster.status` が `not_connected` の間は、各ツールが `next_step_suggestion` で、まだ足りない手順を示します。

1. ドメインを認証します。手順は、上の「ドメイン認証」のとおりです。1回の認証ですべてのデータソースに対応するため、Search Consoleのために認証済みなら、この手順は完了しています。認証するまで、Kafkaiはそのドメインについて何も返しません。Bingのサイトがあるかどうかも返しません。
2. Kafkaiにサイトの読み取り権限を付与します。[Bing Webmaster Tools](https://www.bing.com/webmasters)でサイトを開き、左のメニューの **ユーザーの管理** から **ユーザーを追加** を選択します。KafkaiのBing読み取り用アドレスを入力し、役割に **読み取り専用** を選びます。Bing用の読み取りアカウントはGoogle用とは別なので、アドレスも異なります。アドレスは、ドメイン認証後に `next_step_suggestion` に入ります。手順の詳細は、[Bing Webmaster Toolsを連携する](https://kafkai.com/ja/docs/bing-webmaster-tools/)をご覧ください。

次回の調査実行（`kafkai_update_keywords`）または `kafkai_update_bing_webmaster` の呼び出しのうち、先に行ったほうで、Kafkaiがサイトを検出します。取得は1分以内に終わります。取り込むべき過去の履歴がないためです。Bingは取得のたびに、保持しているデータをすべて返します。最初の取得が終わるまで、ステータスは `syncing` です。

### kafkai_get_bing_webmaster_data

対象サイトがBingで表示された検索クエリ、トラフィックを集めたページ、日別の合計を返します。1週間を、3つのビューで見ます。

- `view='queries'`（既定）：現在の週のBing上位クエリごとに1行です。`query`、`clicks`、`impressions`、`ctr`、`position`、`click_position` に加えて、前の週の値（`prior`）と3つの差分が入ります。
- `view='pages'`：現在の週のBing上位ページごとに1行です。`query` の代わりに `page` が入り、ほかの項目は同じです。
- `view='trend'`：前の週から現在の週までの、新しい側から数えた1日ごとに1行です。古い順に並ぶため、日ごとの変化がわかります。日別の行に掲載順位はありません。全期間を一度に取得するには、`limit=100` を渡します。

すべての応答に、`bing_webmaster`（`property`、`status`、`domain_verified`）、`granularity`、`window`、`prior_window`、`totals`（`current`、`prior`、差分）、`coverage`（常に `null`）、`coverage_note` が入ります。併せて、`kafkai_get_search_console_data` も使います。一方のエンジンで表示回数が多く、もう一方には出てこないクエリは、2つの検索エンジンの違いが実際に表れたものです。

引数：

- `project_id`
- `view`：`queries`（既定）、`pages`、`trend` のいずれか
- `order_by`：queriesビューの並び順。`impressions`（既定）、`clicks`、`position`（表示の平均順位が上位のものから）のいずれか。pagesビューは常に表示回数順です
- `contains`：この文字列を含むクエリ（またはページURL）だけを返します。大文字と小文字は区別しません。trendビューはこの引数を無視し、応答にも含めません
- `limit`：返す最大件数（既定20、最大100）。trendビューでは、新しい日から数えた日数です
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）。trendビューでは、最新の日から数えて過去へさかのぼります

### kafkai_get_bing_webmaster_insights

Bingの上位行について、1週間分を前の週と比べて、Kafkaiが「Bingで最初に取り組むべき点」を計算して返します。指摘は4種類あります。いずれもクエリまたはページ1件です。根拠となる数値（`evidence`）には掲載順位が2つ入り、同じ種類の中で順位付けするための `score` が付きます。

- `striking_distance`：表示の平均順位が1ページ目の少し下（既定では8〜20位）で、表示回数が十分にあるクエリです。scoreは、5位に到達した場合に見込める追加クリック数です。
- `ctr_gap`：Bingでの掲載順位から見込まれる水準を大きく下回るクリック率のクエリです。scoreは、失っているクリック数です。
- `new_query`：今週の上位クエリにあり、前の週の上位クエリにはなかったクエリです。scoreは表示回数です。
- `decay`：前の週と比べて、クリック数が大きく落ちたページです。scoreは、失ったクリック数です。

Bingでは `cannibalisation` を計算しません。1つのクエリを対象サイトのどのページが分け合っているかを、Bingが報告しないためです。応答の `definitions` には、各ルールと適用中のしきい値が入ります。種類ごとの件数は `counts` です。いずれも1週間分のデータです。単独で判断する前に、`kafkai_get_search_console_insights` と照らし合わせてください。

引数：

- `project_id`
- `insight_type`：`all`（既定）、または `striking_distance`、`ctr_gap`、`new_query`、`decay` のいずれか。`all` の場合、`limit` と `offset` は種類ごとに適用します
- `limit`：種類ごとに返す最大件数（既定20、最大100）
- `offset`：種類ごとに読み飛ばす件数。ページ送りに使います（既定0）

### kafkai_update_bing_webmaster

対象サイトのBing Webmaster Toolsの最新データを、調査実行なしで取得します。無料です。

Bingのデータは、調査実行のたびに、その終わりに取得します。このツールは、キーワードと被リンクのデータを買い直さずに、Bingの数値だけを新しくしたいときに使います。Kafkaiに読み取り権限を付与した直後のサイトも、このツールで検出します。接続のために調査実行は必要ありません。

取得はバックグラウンドで行い、1分以内に終わります。Bingは合計を毎日、上位クエリを毎週更新します。そのため、Kafkaiが1つのサイトを取得するのは1日1回までです。24時間以内の2回目の呼び出しでは何も取得せず、次に取得できる時刻を応答で示します。調査実行も、その日の取得として数えます。

先に、上の2つの手順（ドメイン認証と、読み取り権限の付与）が必要です。足りない手順があれば、応答の `next_step_suggestion` が示します。

応答には次の項目が入ります。

- `queued`：取得を開始した場合は `true`、何も取得しなかった場合は `false`
- `bing_webmaster`：`property`、`status`、`domain_verified`。読み取りツールと同じブロックです
- `next_sync_available`：次に取得を開始できる時刻
- `next_step_suggestion`：次に呼び出すツール。通常は、取得の完了後に `kafkai_get_bing_webmaster_data` を示します

引数：

- `project_id`

## トラッキング設定

タグマネージャーが読み込む公開ファイルから、サイトの計測内容を調べます。Googleタグマネージャーの場合、コンテナごとに公開ファイルが1つあり、サイトで配信しているタグが記載されています。Kafkaiは、対象サイトとすべての競合サイトのファイルを読み取ります。これにより、エージェントは競合サイトの集客や販売の手法を説明でき、設定が変わればその内容も報告できます。

このデータから、次の4つがわかります。

- **競合サイトの広告出稿先**：Metaピクセルがあれば、FacebookとInstagramに広告を出しています。Yahoo! JAPANのタグがあれば、Yahoo!広告を利用しています。LinkedInのタグがあれば、法人顧客を狙っています。
- **競合サイトが成果として計測しているもの**：`cv_onlinedemo` や `order_completed` などのイベント名から、どのオファーを試しているかがわかります。
- **競合サイトの販売手法**：マーケティングオートメーションがあれば、営業担当者がリードをフォローしています。チャットツールがあれば、サイト上でリアルタイムに接客しています。アトリビューションツールがあれば、実際に広告費をかけています。
- **変化**：ピクセルが増えれば新しいチャネルへの出稿、イベントが増えれば新しいキャンペーンの開始を示します。

広告費、チャネルごとのトラフィック、リードの価値はわかりません。コンバージョン値がタグに直接書かれていることもまれで、検証した6サイトでは1サイトだけでした。

ファイルにタグの名前は記載されていないため、Kafkaiは、サイトの担当者が付けた名前ではなく、タグの動作を報告します。ベンダー名は、サイトで見つかった表記のまま報告します。

Kafkaiは、調査の最後に毎回サイトを読み取ります。プロジェクトの作成時と更新時はすべてのサイトを、競合サイトの追加時は追加したサイトだけを読み取ります。別のタイミングで読み取るには、`kafkai_update_tracking_stack` を呼び出します。どちらの場合も無料です。Kafkaiが読み取るのは依頼があったときだけで、定期的な確認はしません。

### statusの意味

| `status` | 意味 |
|---|---|
| `ready` | コンテナまたはGoogleタグを1つ以上読み取れました。 |
| `no_tag_manager` | ホームページは読み取れましたが、タグマネージャーもGoogleタグも見つかりませんでした。ページが直接読み込んでいるツールは `vendors` に入ります。 |
| `unreadable` | ホームページを読み取れなかったか、コンテナを1つも読み取れませんでした。 |
| `not_fetched` | このサイトはまだ読み取っていません。 |

`no_tag_manager` も `unreadable` も、サイトがトラッキングをしていないという意味ではありません。次のタグやサイトは、Kafkaiでは確認できません。

- サイト自身のサーバーから配信するタグ（サーバーサイドタグ）
- 同意管理ツールがスクリプトで追加するタグ
- 自動アクセスをブロックしているサイト

応答に `unread_containers` がある場合、読み取れたのは一部のコンテナだけです。

### kafkai_get_tracking_stack

対象サイトと競合サイトのトラッキング設定を返します。無料です。

`domains` の各項目には、次の値が入ります。

- `domain`、`is_own_site`、`status`、`fetched_at`（読み取った日時）
- `containers` と `unread_containers`：ページで見つかったコンテナID
- `ga4_ids`：Google Analytics 4の測定ID
- `ads_account_ids`：Google広告のアカウントID
- `ads_conversion_actions`：Google広告のコンバージョンアクション数
- `literal_conversion_values`：タグに直接書かれたコンバージョン値と `currency`（タグに通貨の指定がなければ `null`）
- `conversion_event_names`：サイトの担当者が入力したとおりのイベント名
- `vendors`：見つかったツール。`ads`、`analytics`、`marketing_automation`、`attribution`、`ab_testing`、`chat`、`other` に分類します。該当するツールがないグループは省略します
- `changes_since_previous`：前回の読み取りから追加・削除された `vendors`、`conversion_event_names`、`ads_account_ids` と、比較対象の読み取り日時（`compared_with`）。初回の読み取り時と、どちらかの読み取りが部分的なときは `null` です。これにより、読み取りの失敗が削除として報告されることはありません
- `last_readable`：`unreadable` のサイトについて、それ以前に読み取れた最新の結果

引数：

- `project_id`
- `domain`：指定したサイトだけを返します。対象サイトまたは競合サイトのドメインを指定します。省略すると、プロジェクトのすべてのサイトを返します

### kafkai_update_tracking_stack

対象サイトとすべての競合サイトを、バックグラウンドで読み取り直します。無料です。過去24時間以内に読み取ったサイトは前回の結果を再利用するため、短い間隔で呼び出しても同じファイルを再取得しません。`unreadable` のサイトは、1時間経過すると再試行できます。

応答には、次の値が入ります。

- `queued`：今回の呼び出しで読み取りを開始したドメイン
- `reused`：直近の結果を再利用したドメイン
- `in_flight`：別の呼び出しで読み取り中のドメイン
- `next_step_suggestion`：次に呼び出すツール。読み取りには1分ほどかかります

引数：

- `project_id`

`kafkai_get_project_summary` と `kafkai_get_competitor_analysis` の `tracking_stack` ブロックには、サイトごとの件数と `changes_since_previous` が入ります。ベンダーとイベントの一覧は、`kafkai_get_tracking_stack` で取得します。

## アナリティクス

対象サイトのアクセス解析データを、1つのツールで読み取ります。Search Consoleが扱うのは検索の側面、つまり何が検索され、どのページがクリックされたかです。アナリティクスは訪問全体を扱います。訪問者数、開かれたページ、訪問のきっかけ、利用環境です。検索データだけでは答えられない問いに答えます。「サイト全体のトラフィックはどれだけあるか」「着いた訪問者は何をするか」の2つです。

データを返すまでに、2つの手順があります。`analytics.status` ブロック（`not_verified`、`not_configured`、`unavailable`、`ready`）は、足りない手順を`next_step_suggestion` で示します。エージェントは、その手順をそのまま案内できます。

1. ドメインを認証します。手順は、上の「ドメイン認証」のとおりです。認証前は、Kafkaiはそのドメインについて何も返しません。アナリティクスの設定があるかどうかも返しません。
2. Kafkaiサポートにトラッキングの設定を依頼します。Kafkaiが管理するアナリティクス環境でトラッキングを設定します。利用者側の作業はありません。設定後の紐付けも不要です。最初の呼び出しで、Kafkaiが対象サイトを自動で見つけて記憶します。設定直後のサイトは、反映まで最長10分かかります。サブドメインのプロジェクトに専用のサイトがない場合は、登録ドメインのサイトを使います。

`unavailable` は、その呼び出しでKafkaiがアナリティクス環境に接続できなかったことを示します。トラッキングの有無とは関係ありません。1分ほど待ってから、もう一度呼び出します。

Search Consoleと違い、待ち時間はありません。データは呼び出しの時点でライブで読み取るため、ステータスが `ready` になれば、次の呼び出しからサイトがその時点で持つ値を返します。

### kafkai_get_analytics_data

トラフィック、ページ、流入元、訪問者の地域と利用環境を、21のレポートで返します。既定では直近30日間を対象にします。日ごとの時系列には、`period='day'` と `date='last30'` を渡します。

すべての応答に、`analytics`（`status`、`domain_verified`、`id_site`、`site_url`）、`report`、レポートの `description`、適用中の `period` と `date`、`count`、`rows` が入ります。続きがある間は、応答の `next_step_suggestion` に次ページの `offset` が入ります。

引数：

- `project_id`
- `report`：`summary`（既定）、`pages`、`entry_pages`、`exit_pages`、`page_titles`、`outlinks`、`downloads`、`referrers`、`search_engines`、`keywords`、`social`、`websites`、`campaigns`、`campaign_sources`、`campaign_contents`、`countries`、`regions`、`cities`、`device_types`、`browsers`、`browser_versions`、`operating_systems`、`screen_resolutions` のいずれか。`summary` は指標1行（訪問数、ユニーク訪問者数、アクション数、直帰率、平均滞在時間）を返します。それ以外は行のリストを返します。広告やタグ付きリンクの効果を見る場合、`campaigns` はキャンペーン名（`utm_campaign`）、`campaign_sources` は参照元とメディア（`utm_source`／`utm_medium`）、`campaign_contents` は広告のバリエーションを区別するコンテンツタグ（`utm_content`）を返します
- `period`：`day`、`week`、`month`、`year`、`range` のいずれか。空の場合は `range` です
- `date`：空の場合は直近30日間です。例：`today`、`last30`、`2024-01-01,2024-01-31`（`period='range'` の場合）
- `segment`：訪問を絞り込むセグメント定義。省略できます
- `limit`：リスト型レポートの最大件数（既定20、最大100）。`summary` では無視します
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）

### kafkai_get_ga_analytics_data

顧客自身のGoogle Analytics 4データ：トラフィック、ページ、ランディングページ、チャネル、流入元/メディア、国、都市、デバイス、ブラウザ、OS、コンバージョンイベント。顧客のGA4プロパティからライブで読み取ります。保存しないため、アクセスを許可すれば同期や待ち時間は不要です。

Search Consoleやアナリティクスと同じドメイン認証ゲートです。`ga_analytics.status` ブロック（`not_verified`、`not_connected`、`ambiguous`、`unavailable`、`ready`）が `next_step_suggestion` でまだ足りない手順を示します。

1. ドメインを認証します（上記「ドメイン認証」を参照）。
2. Google Analyticsで、管理 › プロパティのアクセス管理 › ユーザーを追加と進み、Kafkaiのリーダーアドレスを入力して閲覧者ロールを選択します。次回のツール呼び出しでプロパティが見つかります。リサーチ実行は不要です。

`ambiguous` は複数のGA4プロパティが同じサイトを主張している状態です。使うプロパティIDをKafkaiサポートにお伝えください。

引数：

- `project_id`
- `report`：`summary`（既定）、`daily`、`pages`、`landing_pages`、`channels`、`source_medium`、`organic_landing_pages`、`countries`、`cities`、`devices`、`browsers`、`operating_systems`、`key_events` のいずれか。`summary` は1行のメトリクス行を返し、それ以外は行のリストを返します。
- `start_date`：ISO日付（`2026-08-01`）またはGA4の相対日付（`30daysAgo`、`yesterday`、`today`）。空の場合は30daysAgo。
- `end_date`：ISO日付またはGA4の相対日付。空の場合はyesterday。
- `limit`：最大件数（既定20、最大100）。`summary` では無視します。
- `offset`：読み飛ばす件数。ページ送りに使います（既定0）

## SERPインテリジェンス

### kafkai_get_keyword_serp_data

キーワード1件について、プロジェクト内の情報をすべて返します。上位表示中のドメイン、タイトル、説明文、URL種別、対象サイトの順位、競合の順位、順位の変動、検索ボリューム、難易度、CPC、タグです。応答には `ranking_context` として、状況の解釈も含まれます。たとえば「競合が3位、対象サイトは圏外。この需要を獲得する記事が必要」という形です。完全一致するキーワードがない場合は、部分一致の候補を返します。基本料金は高めです。

引数：

- `project_id`
- `keyword`：対象のキーワード（完全一致を優先し、なければ部分一致）

### kafkai_check_search_results

指定したキーワードについて、Googleの検索結果の1ページ目に出ているサイトを確認します。対象は、プロジェクトの国と言語の検索結果です。前回の確認からの変化も返します。主要なキーワードで上位に出るサイトの監視に使います。対象サイトが1ページ目にあるか、どの比較サイトやレビューサイトが出ているか、先週からどのサイトが入れ替わったかがわかります。

`kafkai_get_keyword_serp_data` との違いは2点です。対象サイトと競合サイトだけでなく、1ページ目のすべてのサイトを返します。また、プロジェクトの調査データにないキーワードも確認できます。

`checks` には、キーワードごとに1件の結果が入ります。

- `keyword`：確認したキーワード（前後の空白を除き、小文字にした値）
- `checked_at`：Kafkaiがページを取得した日時
- `fetched_fresh`：この呼び出しで取得した場合は `true`、直近24時間以内に保存したページを返した場合は `false`
- `own_site_position`：ページ内での対象サイトの最上位の順位。1ページ目で見つからなかった場合は `null`。`note` に値がある場合、`null` は「1ページ目にない」という意味ではありません
- `unread_addresses`：Kafkaiがアドレスを読み取れなかった結果の件数。すべて読み取れたページでは `0`
- `note`：読み取れなかったアドレスがあるために判定できない内容。ない場合は `null`
- `results`：1ページ目のオーガニック検索結果（最大10行）
- `changes`：前回保存したページからの変化。そのキーワードを初めて確認した場合と、前回のページに読み取れたアドレスが1件もない場合は `null`

`results` の各行には、`position`（オーガニック検索結果の中での順位）、`rank_absolute`（広告などを含む、ページ内のすべての要素の中での順位。キーワードのツールが返す値と同じ）、`domain`、`url`、`title`、`description` と、次の3つのフラグが含まれます。

- `is_own_site`：対象サイトの結果
- `is_tracked_competitor`：プロジェクトに登録済みの競合サイトの結果
- `links_to_own_site`：Kafkaiの被リンクデータに、そのサイトから対象サイトへの有効なリンクがある。被リンクデータは標本で、どこまで網羅しているかは `own_site_backlink_coverage` が示します。`false` は「標本の中にリンクがない」、`null` は「対象サイトの被リンクデータが未取得」の意味です。アフィリエイトASPのリダイレクト用ドメインを経由するリンクは検出しません

**Kafkaiがアドレスを読み取れなかった場合**。Kafkaiが検索結果のアドレスを読み取れないことがあります。その行の `title` と `description` は正しい値ですが、次の点が異なります。

- `domain` は `null` です。
- `is_own_site`、`is_tracked_competitor`、`links_to_own_site` は `null` です。`false` ではなく、「不明」の意味です。
- `url` は、ページ自体のアドレスではなく、Googleがそのページに付けたリンクです。

`domain` に値があっても、`url` がGoogleのリンクのままの行もあります。この場合、Kafkaiは検索結果のパンくずリストからサイトを読み取っています。

読み取れた行の中に対象サイトがなく、読み取れなかったアドレスが1件以上ある場合、`own_site_position` は `null` になります。このとき `note` が、対象サイトが1ページ目にある可能性を伝えます。エージェントは、`domain` が `null` の行のタイトルを確認してから、対象サイトの有無を報告します。読み取れなかった行が対象サイトより上にある場合、`note` が、対象サイトの実際の順位は `own_site_position` より上の可能性があることを伝えます。

`changes` には、`previous_checked_at` と3つの一覧が入ります。比較はサイト単位です。`entered` は新しく1ページ目に入ったサイト、`left` は1ページ目から外れたサイト、`moved` は順位が変わったサイトです。`change` は、順位が上がった場合に正の値になります。読み取れなかったアドレスがあると、判定できない一覧があります。Kafkaiは推測せず、その一覧を `null` にします。前回のページに読み取れなかったアドレスがある場合は `entered` が、最新のページにある場合は `left` が `null` になります。どちらかのページにある場合は、`moved` も `null` になります。

次の4点に注意します。

- **Kafkaiが確認するのは、ツールを呼び出したときだけです**。定期的な自動実行はありません。変化を追う場合は、同じキーワードでツールを再度呼び出します（たとえば週に1回）。
- **直近24時間以内に保存したページは、そのまま返します**。再取得はせず、そのキーワードの料金もかかりません。
- **Kafkaiが返すのは、どのサイトが出ているかです。ページの内容は読み取りません**。比較ページにサービスが掲載されているか、何番目に掲載されているかは、エージェントが行の `url` を開いて確認します。
- **取得に失敗したキーワードは `failed` に入り、課金しません**。アドレスを1件も読み取れなかったページも、取得の失敗として扱います。再度呼び出すと、取得し直します。

料金は、1回の呼び出しにつき1クレジットに、Kafkaiが新しく取得したキーワード1件ごとに5クレジットを加えた額です。キーワード10件の呼び出しは、最大51クレジットです。保存済みのページだけを返した呼び出しは、1クレジットです。拒否された呼び出しと、ページを1件も返せなかった呼び出しは、無料です。課金額は、応答の `billing` に入ります。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。

引数：

- `project_id`
- `keywords`：確認するキーワードのリスト。1回の呼び出しで10件まで。11件以上のリストは拒否します

## マーケットプレイス

プロジェクトはWebサイトです。Amazonなどのマーケットプレイスは、同じ事業のもう1つの販売チャネルです。ここの2つのツールは、「Amazonで商品が何位に出ているか」「このキーワードのGoogleショッピングにどの販売者が出ているか」に答えます。設定は変わりません。プロジェクトはドメインごとに1つのままです。ツールを呼び出すまで、Kafkaiは何も実行しません。

対応しているマーケットプレイスは2つです。

| `marketplace` | Kafkaiが取得するもの |
|---|---|
| `amazon` | Amazonの検索結果 |
| `google_shopping` | Googleショッピングの検索結果 |

キーワードは、ツールを呼び出す側が指定します。Kafkaiは、商品が上位表示されているキーワードの一覧を持っていません。

### kafkai_check_marketplace_results

指定したキーワードについて、マーケットプレイスの検索結果に出ている商品を確認します。対象は、プロジェクトの国の検索結果です。前回の確認から対象サイトの商品の順位が動いたかどうかも返します。ネットショップの確認に使います。あるキーワードで、Amazonの何位に商品が出ているかがわかります。その上にどの商品がいくらで出ているかも、わかります。Googleショッピングにどの販売者が出ているかも、わかります。

`checks` には、キーワードごとに1件の結果が入ります。

- `keyword`：確認したキーワード（前後の空白を除き、小文字にした値）
- `fetched_at`：Kafkaiがページを取得した日時
- `served_from_store`：この呼び出しで取得した場合は `false`、保存済みのページを返した場合は `true`
- `result_count`：保存したページ全体の商品数
- `own_listing_position`：対象サイトの商品（広告を除く）の最上位の `rank_absolute`。ページにない場合と、識別情報が未登録の場合は `null`
- `own_listings`：ページ内の対象サイトの商品すべて。`limit` 件を超える行も含みます
- `results`：ページの上から `limit` 件の商品
- `change_since_previous`：現在の順位と、前回保存したページでの順位。そのキーワードを初めて確認した場合は `null`

`results` の各行には、次の項目が含まれます。

- `rank_absolute`：広告を含む、ページ内のすべての商品の中での順位
- `rank_group`：同じ種類（`type`）の行の中での順位
- `type`：`organic`（通常の検索結果）または `sponsored`（広告）
- `listing_id`：AmazonではASIN。GoogleショッピングではGoogleの商品ID（IDのない行では空）
- `title`、`url`、`price`、`currency`、`rating`、`rating_count`
- Amazonのみ：`is_amazon_choice`、`is_best_seller`、`bought_past_month`
- Googleショッピングのみ：`seller`（Googleが表示する販売者名）
- `is_own_listing`：Amazonでは、プロジェクトのASINを登録済みの場合は `true` または `false` です（`kafkai_set_marketplace_identity` を参照）。完全一致で判定します。ASINが未登録の場合は `null`。Googleショッピングでは常に `null` のため、`seller` の販売者名で判断します

`change_since_previous` には、`previous_fetched_at`、`own_listing_position`、`previous_own_listing_position`、`change` が入ります。`change` は、順位が上がった場合に正の値になります。どちらかのページに商品がない場合は `null` です。

応答の返し方は、マーケットプレイスによって異なります。

- **Amazonは、1回の呼び出しで結果を返します**。呼び出しには約20秒かかります。
- **Googleショッピングは、2回の呼び出しで結果を返します**。1回目は取得を予約し、キーワードを `pending` に入れて返します。約1分後に同じキーワードで再度呼び出すと、ページを読み取れます。Googleショッピングの料金は、ページが届いた2回目の呼び出しでかかります。すべてのキーワードがまだ取得中の場合、呼び出しは無料です。

次の7点に注意します。

- **Kafkaiが確認するのは、ツールを呼び出したときだけです**。定期的な自動実行はありません。プロジェクトの作成時や調査の実行時にも、確認は行いません。
- **直近24時間以内に保存したページは、そのまま返します**。再取得はせず、そのキーワードの料金もかかりません。
- **Kafkaiが返すのは、どの商品が出ているかです**。どの商品が安いか、どの商品のレビューが多いかは、エージェントが行を読んで判断します。
- **商品が1件もないページも、結果の1つです**。そのキーワードでは、マーケットプレイスに商品が表示されていません。Kafkaiは `result_count` が0の結果を返し、ほかのページと同じように課金します。
- **取得に失敗したキーワードには、課金しません**。Amazonでは `failed` に入ります。再度呼び出すと、取得し直します。
- **Googleショッピングのキーワードは、ページが届いた時点で課金します**。取得の予約は無料ですが、残高が、その呼び出しで返すページの料金以上である必要があります。Kafkaiは、各ページを初めて返した呼び出しで課金します。取得に失敗した場合は、次回そのキーワードで呼び出したときに取得し直し、`retried` に入れて返します。取得し直すのは2回までです。それでも取得できなかったキーワードは `failed` に入り、Kafkaiは24時間、そのキーワードを取得しません。
- **未読のGoogleショッピングのページには、プロジェクトごとに上限があります**。取得を予約したページと、届いたもののまだ返していないページが、未読です。上限を超えて予約する呼び出しは拒否されます。課金はせず、上限の件数を示し、未読のキーワードを `unread` に入れて返します。その場合、エージェントは先に `unread` のキーワードで呼び出し、ページを読み取ります。1回の呼び出しで未読のページを読み取ると、読み取った件数と同じ数だけ、新しいキーワードを同じ呼び出しで予約できます。

料金は、1回の呼び出しにつき1クレジットに、まだ一度も返していないページ1件につき5クレジットを加えた額です。キーワード10件の呼び出しは、最大51クレジットです。支払い済みのページだけを返した呼び出しは、1クレジットです。拒否された呼び出しと、ページを1件も返さなかった呼び出しは、無料です。そのため、Googleショッピングのキーワードの取得の予約と、取得中（`pending`）のキーワードを確認する呼び出しは、どちらも無料です。課金額は、応答の `billing` に入ります。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。

引数：

- `project_id`
- `marketplace`：`amazon` または `google_shopping`
- `keywords`：確認するキーワードのリスト。1回の呼び出しで10件まで。11件以上のリストは拒否します
- `limit`：キーワードごとに返す行数。ページの上から数えます（既定20、最大100）。Kafkaiは、この値にかかわらずページ全体を保存します

対応国は次のとおりです。プロジェクトの国が、そのマーケットプレイスの対応国である場合に利用できます。

| `marketplace` | 対応国（プロジェクトの国） |
|---|---|
| `amazon` | 日本、アメリカ、イギリス、ドイツ、フランス、カナダ、オーストラリア、インド、ブラジル、アラブ首長国連邦、シンガポール |
| `google_shopping` | 日本、アメリカ、イギリス、ドイツ、フランス、カナダ、オーストラリア、インド、ブラジル、アラブ首長国連邦、韓国、シンガポール、マレーシア、インドネシア、タイ、デンマーク、ポルトガル |

それ以外の国のプロジェクトでは、Kafkaiは呼び出しを拒否します。課金もしません。

### kafkai_set_marketplace_identity

マーケットプレイス上のどの商品がプロジェクトのものかを、Kafkaiに登録します。マーケットプレイスはドメインを持たないため、Kafkaiは登録されたIDと行を照合します。無料です。

- `amazon` の場合は `asins` を指定します。対象サイトの商品のASINです。ASINは、商品ページのURLの `/dp/` に続く10桁の英数字です。登録後は、`kafkai_check_marketplace_results` がAmazonのすべての行に `is_own_listing` を設定します。保存済みのページも対象です。
- `google_shopping` の場合は `seller_name` を指定します。Googleショッピングが表示する販売者名です。Kafkaiは販売者名を保存しますが、現時点では行との照合には使いません。

指定した値で、登録済みの値を置き換えます。毎回すべてのリストを指定します。消去する場合は、空のリストを指定します。`asins` も `seller_name` も指定せずに呼び出すと、登録済みの値を読み取れます。

このツールにドメイン認証は不要です。検索結果のページは公開情報で、このリストはKafkaiがどの行にフラグを付けるかを決めるだけです。登録しなくても、`kafkai_check_marketplace_results` は使えます。その場合、すべての行の `is_own_listing` が `null` になります。

引数：

- `project_id`
- `marketplace`：`amazon` または `google_shopping`
- `asins`：Amazonのみ。プロジェクトのASINすべてのリスト。200件まで
- `seller_name`：Googleショッピングのみ。販売者の表示名

## プロジェクト管理

データを変更するツールです。調査は非同期で実行します。実行を指示したあとは作業を続け、`kafkai_get_project_summary` で結果を確認します。

### kafkai_create_project

サイトのプロジェクトを作成し、競合サイトを登録し、キーワード調査全体をキューに登録します。対象サイトと各競合サイトの被リンクも、同じ調査で取得します（[被リンク](#被リンク)を参照）。料金は調査するサイトの数で決まります。対象サイトの基本料金に、登録する競合サイト1件ごとの競合料金を加えた額です。詳しくは[クレジットと料金](https://kafkai.com/ja/docs/credits/)をご覧ください。

引数：

- `site_url`：分析対象のサイト（例：`https://hogehoge.jp`）。必須
- `site_name`：表示名。省略時はURLを使用
- `description`：サイトの簡単な説明
- `location_code`：対象とする国の検索結果。必須で、既定値はありません。2のあとにISO 3166-1の数字コードを続けた値です。日本は `2392`、マレーシアは `2458`、米国は `2840`。指定せずに呼び出した場合は課金されずにエラーとなり、選択できる市場の一覧を返します
- `competitors_url`：競合サイトURLのリスト。省略可能

競合サイトの登録は必須ではありません。あとから `kafkai_add_competitor` で追加できます。登録がない場合、Catch-up、Consolidate、Competeは空のままです。いずれも比較する競合が必要なためです。一方でKafkaiは、対象サイトの掲載順位とComplementキーワードを取得します。ドメインと国だけでも、プロジェクトは役に立ちます。

Kafkaiは、プロジェクトを作成する前に、競合サイトのドメインまたはホスト名がすべて解決できるか確認します。解決できないドメインが1件でもあると、呼び出しを受け付けません。プロジェクトは作成されず、クレジットも消費しません。応答の `unreachable_competitors` に、該当するURLが入ります。URLを直すか一覧から外して、もう一度呼び出します。

プロジェクトは1つの国に固定されます。対象外の国を調査しても料金は同じで、得られるものはありません。だからKafkaiは推測せず、国を必ず指定させます。

応答には `setup_steps` が含まれます。Kafkaiがサイトの独自データを読めるようにする手順を、実行順に並べたリストです。各手順には、`step`（手順名）、`title`（見出し）、`instructions`（使うツールやページ）、`requires`（先に済ませる手順。不要な場合は `null`）があります。

1. `verify_domain`：`kafkai_verify_domain` を呼び出します。返ってきたDNSのTXTレコードかメタタグを設置したら、`kafkai_check_domain_verification` を呼び出します。アカウントのドメインページでも同じ操作ができます。詳しくは[ドメイン認証](#ドメイン認証)を参照してください
2. `connect_search_console`：Search Consoleのプロパティに、Kafkaiの読み取り用アドレスを「制限付き」として追加します
3. `connect_google_analytics`：Google Analyticsのプロパティに、Kafkaiの読み取り用アドレスを「閲覧者」として追加します
4. `connect_analytics`：Kafkaiのアナリティクスのトラッキング設定を、Kafkaiサポートに依頼します。トラッキングの設定後は、Kafkaiが対象サイトを自動で検出します
5. `connect_bing_webmaster`：Bing Webmaster Toolsのサイトに、KafkaiのBing用読み取りアドレスを「読み取り専用」として追加します

どの手順も無料です。実行は任意です。対象サイトを所有していない場合や、使っていないサービスがある場合は、その手順を飛ばして構いません。手順2〜5は、手順1が済んでから行えます。すでに済んでいる手順はリストに入りません。たとえば、同じアカウントが別のプロジェクトでドメインを認証済みの場合です。リストの説明は `setup_steps_note` に入ります。プロジェクトがすでに存在する場合も、同じリストが返されます。

### kafkai_add_competitor

既存のプロジェクトに競合サイトを1件追加し、その競合の分だけキーワードと被リンクのデータを取得します。登録済みの競合と対象サイトは再取得しないため、全体更新より費用を抑えられます。かかるのは競合料金1件分です。

調査はバックグラウンドで実行され、全体更新と同じように記録されます。応答には `update_log_id` が含まれます。数分後に `kafkai_list_competitors` で確認します。データが揃うと、競合の `status` は `ready` になります。失敗した場合は `failed` になり、理由が `error` に入ります。調査の実行中は、`kafkai_update_keywords` と削除ツールを受け付けません。

Kafkaiは、最初に競合サイトのドメインまたはホスト名が解決できるか確認します。解決できない場合は、呼び出しを受け付けず、クレジットも消費しません。エラーは「Kafkai could not reach this site. Check the address and try again.」です。ドメインまたはホスト名が解決できるサイトは、パーキングページやエラーを返しても受け付けます。

引数：

- `project_id`
- `competitor_url`

### kafkai_delete_competitor

プロジェクトから競合サイトを1件削除します。その競合について収集したキーワードと、各キーワードの順位の推移も、すべて削除の対象です。誤って追加した競合サイトの無関係なキーワードを、一覧から取り除くときに使います。無料です。

削除は取り消せないため、このツールは2段階で実行します。

1. `confirmation_token` を指定せずに呼び出します。この時点では、何も削除されません。応答には、削除される内容と残る内容が含まれます。削除される内容は、戦略ごとのキーワード数、調査セッション、順位の推移です。あわせて、15分間有効な`confirmation_token` も返します。
2. エージェントがその内容を提示し、削除してよいか確認します。承認後に、もう一度呼び出します。このとき、同じ `project_id` と`competitor_domain` に加えて、`confirmation_token` を指定します。競合サイトは削除予定の状態になり、データはバックグラウンドで削除されます。数分後に `kafkai_list_competitors` で、結果を確認します。

トークンは、1つの競合サイトと1つのアカウントに結び付いています。別の競合サイトに使い回した場合や、有効期間を過ぎた場合は、拒否されて何も起こりません。プロジェクトの順位更新が実行中の間は、削除を受け付けません。更新の完了後に、もう一度依頼します。

引数：

- `project_id`
- `competitor_domain`：`kafkai_list_competitors` が返すドメイン。ドメインの代わりにURL全体を指定することもできます。
- `confirmation_token`：プレビューでは空のままにします。削除を実行するには、プレビューの応答に含まれるトークンを指定します。

### kafkai_update_keywords

プロジェクト全体の順位更新をキューに登録します。全戦略と対象サイトの掲載順位を取得し直し、既存キーワードの順位を更新し、圏外になったキーワードに印を付けます。各キーワードの順位の推移に次の1点が加わるのも、この更新です。変化を確認する前に実行します。確認には `kafkai_get_ranked_keywords` や `kafkai_get_ranking_changes` を使います。対象サイトとすべての競合サイトの被リンクも、同じ更新で取得し直します（直近1日以内に取得したサイトは再利用します）。対象サイトのホームページも、更新の開始時に読み取り直します。そのため、`kafkai_get_project_summary` の `site_metadata` は現在のページを示します。ホームページを読み取れなくても、更新は失敗しません。料金は作成時と同じ計算です。対象サイトの基本料金に、プロジェクト内の競合サイト1件ごとの競合料金を加えた額です。同時に実行できる調査は、1つのプロジェクトにつき1件です。競合サイト追加時の調査も含めて、実行中の再依頼は拒否されます。削除を確定したプロジェクトも更新できません。この依頼は、課金の前に拒否されます。更新は指示したときだけ実行します。Kafkaiが自動的に順位を再取得することはありません。

引数：

- `project_id`

### kafkai_delete_project

プロジェクトを、関連データごと削除します。競合サイト、各キーワードと順位の推移、調査セッションがすべて対象です。不要になったプロジェクトや、誤ったサイトで作成したプロジェクトを削除するときに使います。無料です。

削除は取り消せないため、このツールは2段階で実行します。

1. `confirmation_token` を指定せずに呼び出します。この時点では、何も削除されません。応答には、削除される内容と残る内容が含まれます。削除される内容は、競合サイト、戦略ごとのキーワード数、調査セッションの数です。あわせて、15分間有効な`confirmation_token` も返します。
2. エージェントがその内容を提示し、削除してよいか確認します。承認後に、もう一度呼び出します。このとき、同じ `project_id` に加えて、`confirmation_token` を指定します。プロジェクトは削除中の状態になり、データはバックグラウンドで削除されます。数分後に`kafkai_list_projects` で、結果を確認します。

トークンは、1つのプロジェクトと1つのアカウントに結び付いています。別のプロジェクトに使い回した場合や、有効期間を過ぎた場合は、拒否されて何も起こりません。公開先のサイトに公開済みの記事は、そのまま残ります。公開先と公開の記録はアカウントに属するため、削除されません。プロジェクトの順位更新が実行中の間は、削除を受け付けません。更新の完了後に、もう一度依頼します。

引数：

- `project_id`
- `confirmation_token`：プレビューでは空のままにします。削除を実行するには、プレビューの応答に含まれるトークンを指定します。

### 設定のリマインダー

プロジェクトの作成時に設定の手順を飛ばしても、Kafkaiはその手順を案内し続けます。`kafkai_get_project_summary` と `kafkai_list_projects` の応答には、`setup_reminders` が入ります。まだ完了していない設定手順を、ドメイン認証、Search Console、Google Analytics、アナリティクス、Bing Webmaster Toolsの順に並べたリストです。各項目には、`step`（手順名）、`title`（見出し）、`instructions`（`kafkai_create_project` の `setup_steps` と同じ説明）、`mute`（このリマインダーを停止する呼び出し）があります。`setup_reminders_note` は、リマインダーを毎回ではなく、セッションごとに1回だけ伝えるようエージェントに指示します。

- ドメイン認証が済むまでは、リマインダーは `verify_domain` だけです。ほかの手順は、ドメイン認証が先に必要です。
- 完了した手順は、リストに含まれません。停止したあとに接続したデータソースも、リストに含まれません。
- 停止したデータソースも、リストに含まれません。すべてのデータソースのリマインダーを停止すると、ドメイン認証のリマインダーも表示されなくなります。
- Kafkaiが接続できなかったデータソースは、リストに含まれません。そのデータソースのブロックに、再試行を促す内容が表示されます。
- 正確な情報は、`kafkai_get_project_summary` の応答です。`kafkai_list_projects` は保存済みのデータだけを読みます。そのため、サマリーでは完了済みのGoogle Analyticsやアナリティクスの手順が、一覧に残ることがあります。新しいプロパティやサイトを検出するのはサマリーのみで、一覧では検出しません。エージェントは、プロジェクトのリマインダーを伝える前に、そのプロジェクトのサマリーを呼び出します。

### kafkai_update_project_settings

プロジェクトの設定を変更します。現在の設定項目は `setup_reminders` だけです。プロジェクトで表示する設定のリマインダーを選びます。対象サイトを所有していない場合や、使っていないサービスがある場合は、エージェントに「example.comのGoogle Analyticsのリマインダーを止めて」のように依頼します。無料です。

止めるのはリマインダーの表示だけです。接続は解除しません。データも変更されません。停止したデータソースをあとで接続する場合は、これまでと同じ設定の手順で接続します。アカウントのプロジェクトページの「外部連携」には、停止したデータソースのうち未接続のものに「リマインダー停止中」と表示されます。このページに切り替えのボタンはありません。設定の変更は、エージェントを通して行います。

引数：

- `project_id`
- `setup_reminders`：変更するデータソースと、その表示／非表示の設定値。`true`（案内する）か `false`（止める）を指定します。例：`{"google_analytics": false}`。データソース名は `search_console`、`google_analytics`、`analytics`、`bing_webmaster` です。指定しないデータソースは、現在の設定のままです。引数を省略すると、現在の設定をそのまま返します

応答には、`settings.setup_reminders`（データソースごとのリマインダーの有無）と、表示中の `setup_reminders` が入ります。不明なデータソース名を指定した場合は、有効な名前の一覧を返して拒否します。設定は変わりません。

## 公開

Kafkaiは記事を書きません。エージェントが上記のデータをもとに記事を書き、完成した本文をKafkaiに渡して公開します。Kafkaiが保持するのは、送信した内容そのもの（タイトル、本文、言語）の記録だけです。記事の別の写しは持ちません。

WordPressサイトを公開先に設定する手順は、[WordPressを連携する](https://kafkai.com/ja/docs/wordpress/)をご覧ください。書き込み権限のあるWordPressユーザー名と、アプリケーションパスワードが必要です。WordPressのログイン用パスワードは使用できません。

### kafkai_list_publishing_destinations

アカウントに登録した有効な公開先（WordPressサイトとWebhook）の一覧を返します。各公開先の `destination_id`、名前、種類、URLを含みます。公開先はプロジェクトではなくアカウントに属します。無料です。

引数：なし

### kafkai_add_publishing_destination

公開先を追加します。WordPressの場合はサイトのURLとアプリケーションパスワードを、Webhookの場合はエンドポイントのURLと認証情報を指定します。認証情報は暗号化して保存し、応答には含めません。無料です。

引数：

- `name`：公開先の名前（アカウント内で一意）
- `destination_type`：`wordpress`（既定）または `webhook`
- `url`：サイトまたはエンドポイントのURL
- `auth_type`：`basic`（既定）。送信できるのはBasic認証だけなので、選択肢もBasic認証だけです。
- `credentials`：認証方式に対応するログイン情報。WordPressの場合は `username` と `password` を指定します。`password` にはアプリケーションパスワードを指定します。WordPressのログイン用パスワードは使用できません。どちらかが欠けている場合、呼び出しは拒否されます。Webhookの場合は `username`（または `email`）と `password` を指定します。KafkaiはHTTP Basic認証として送信します。指定がない場合、Webhookは認証なしで呼び出されます。他の認証方式にはまだ対応していません。

### kafkai_delete_publishing_destination

公開先を削除します。その公開先に公開済みの記事はそのまま残り、公開の記録も保持します。無料です。

引数：

- `destination_id`

### kafkai_publish_article

エージェントが書いた本文を1つの公開先に公開し、公開先のURL（`external_url`）を返します。本文はHTMLを `content` に、またはMarkdownを `content_markdown` に指定します。`content` が空の場合はMarkdownをHTMLに変換して送信します。Webhookの公開先にはMarkdownもそのまま渡します。`post_status` に `live` を指定しない限り下書きとして公開するため、公開前にサイト上で内容を確認できます。無料です。

既存の投稿を更新する場合は、その `external_id`（以前の公開呼び出しで返された値）を指定してください。新しい投稿を作成せず、既存の投稿が編集されます。

1つの記事を複数の言語で公開するには、言語ごとに1回ずつツールを呼び出し、`language`（`en`、`ja`）を指定します。すべての言語版に同じ `slug` を指定します。kafkai.aiなどの受信側は、スラッグを使って各言語版を翻訳として関連付けます。後から1つの言語版を更新するには、その言語の呼び出しで返された `external_id` を指定します。

引数：

- `project_id`：記事の対象プロジェクト。既定の言語は、このプロジェクトの対象地域から決まります。
- `destination_id`：`kafkai_list_publishing_destinations` が返す値
- `title`
- `content`：HTMLの本文。`content_markdown` を指定しない場合は必須
- `content_markdown`：Markdownの本文
- `language`：`en` や `ja` など。既定はプロジェクトの対象地域の言語
- `post_status`：`draft`（既定）または `live`
- `categories`：カテゴリ名（例：`["Education", "Coffee"]`）。WordPressでは、存在しないカテゴリは自動作成されます。Webhookの公開先にはそのまま転送されます。
- `slug`：投稿のURLスラッグ（例：`my-first-article`）。Webhookの公開先にはそのまま転送されます。1つの記事のすべての言語版に、同じスラッグを指定します。
- `external_id`：既存の投稿を更新する場合、その投稿のID。同じ言語の以前の公開呼び出しで返された `external_id` を使用してください。省略時は新規投稿が作成されます。
- `author`：著者のメールアドレスまたは表示名。公開先に登録されている値を指定します。255文字まで
- `excerpt`：記事一覧に表示する短い要約。2,000文字まで
- `seo_title`：検索結果に表示するタイトル（HTMLの `<title>`）。`title` と異なる場合に指定します。255文字まで
- `meta_description`：検索結果で見出しの下に表示するテキスト。2,000文字まで
- `featured_image_url`：アイキャッチ画像の公開URL（`http` または `https`）。2,000文字まで。受信側が画像をダウンロードします。ホストがプライベート、ローカル、内部のアドレスの場合（`localhost`、`10.0.0.5`、そのようなアドレスに解決される名前）は拒否します。受信側が自身のネットワークから画像をダウンロードすることはありません。

これらの条件を満たさない値は、保存と送信の前に拒否されます。

`author`、`excerpt`、`seo_title`、`meta_description`、`featured_image_url` は、Webhookの公開先にだけ送信します。WordPressの公開先では、現時点ではこれらを使用しません。Kafkaiは5項目すべてを、タイトルや本文とあわせて公開の記録に保存します。受信側によっては、`author` と `slug` が必須です。kafkai.aiでは両方が必須です。

### Webhookのリクエストとレスポンス

この節は、Webhookの受信側を開発する方向けです。

**リクエスト**：Kafkaiは、`kafkai_publish_article` の呼び出しごとに、公開先のURLへ `POST` を1回送信します。

- ヘッダー `Content-Type: application/json`
- 公開先に `username`（または `email`）と `password` がある場合は、HTTP Basic認証（`Authorization: Basic …`）。ない場合、`Authorization` ヘッダーは送信しません。
- 署名ヘッダーはありません。
- Kafkaiはレスポンスを30秒間待ちます。再試行はしません。タイムアウトまたはエラーのレスポンスの場合、呼び出しは失敗します。

JSONの本文：

| フィールド | 送信する場合 | 値 |
|---|---|---|
| `title` | 常に | 投稿のタイトル |
| `content` | 常に | HTMLの本文。エージェントがMarkdownだけを指定した場合は、`content_markdown` から変換した値 |
| `status` | 常に | `draft` または `live` |
| `content_markdown` | 空でない場合 | エージェントが書いたままのMarkdownの本文 |
| `language` | 空でない場合 | `en`、`ja` などの言語コード |
| `slug` | 空でない場合 | URLスラッグ。1つの記事のすべての言語版で共通 |
| `categories` | 空でない場合 | カテゴリ名のリスト |
| `author` | 空でない場合 | 著者のメールアドレスまたは表示名 |
| `excerpt` | 空でない場合 | 記事一覧用の短い要約 |
| `seo_title` | 空でない場合 | 検索結果用のタイトル |
| `meta_description` | 空でない場合 | 検索結果で見出しの下に表示するテキスト |
| `featured_image_url` | 空でない場合 | ダウンロードする画像の公開URL（`http`/`https`） |
| `external_id` | 更新時のみ | 更新する投稿のID |

例：

```json
{
  "title": "How to build an AI strategy",
  "content": "<p>Rendered HTML</p>",
  "content_markdown": "Markdown body",
  "status": "live",
  "language": "en",
  "slug": "build-ai-strategy",
  "author": "writer@example.com",
  "categories": ["AI Strategy"],
  "excerpt": "One or two sentences for listings.",
  "seo_title": "How to Build an AI Strategy | Example",
  "meta_description": "Text shown under the headline in search results.",
  "featured_image_url": "https://example.com/hero.jpg",
  "external_id": "123"
}
```

**レスポンス**：Kafkaiは、ステータス `200`、`201`、`202` とJSONの本文（`Content-Type: application/json`）を受け付けます。

- `id`（または `external_id`）：必須。受信側での投稿のID。Kafkaiはこの値を `external_id` としてエージェントに返します。
- `url`：投稿の公開URLまたはプレビューURL。Kafkaiはこの値を `external_url` としてエージェントに返します。ない場合は、WebhookのURLを返します。

それ以外のステータスの場合、呼び出しは失敗します。エラーの本文がJSONの場合、Kafkaiはその `error` または `message` フィールドをエージェントに示します。成功のステータスでも、本文がHTMLの場合、JSONでない場合、IDがない場合は失敗します。

**更新**：更新も、同じURLへの同じ `POST` です。本文に `external_id` が含まれます。受信側は `external_id` で作成と更新を判断します。ある場合はその投稿を変更し、ない場合は新しい投稿を作成します。

**言語**：1回の呼び出しで、1つの言語版を送信します。英語版と日本語版がある記事は、`slug` が同じで `language` が異なる2回のリクエストになります。受信側はスラッグで各言語版を関連付け、それぞれに異なる `id` を返します。後で各言語版を更新するときは、それぞれの `id` を使います。

## アカウント

### kafkai_get_account

この接続が使っているKafkaiアカウントを返します。無料です。

複数のKafkaiアカウントをエージェントに接続している場合は、エージェントに「どのKafkaiアカウントに接続している？」と聞きます。エージェントがこのツールを呼び出して答えます。複数の接続があると伝えておけば、クレジットを消費するツールの前にもこのツールを呼び出し、どのアカウントが支払うかを確認できます。

返す項目：

- `email`：Kafkaiへのログインに使うメールアドレス
- `name`：アカウント名。未設定の場合は空です。
- `connection`：エージェントの接続方法。`type` は `oauth`（Kafkai上でエージェントを承認した接続）または `api_token`（Kafkaiで発行したトークンを貼り付けた接続）です。`label` はエージェント名またはトークン名、`authorized_at` は接続した日時です。
- `credit_balance`：アカウントのクレジット残高

Kafkaiはこれらの情報を接続そのものから読み取ります。引数がないため、ほかのアカウントの情報は返しません。チームのチャットボットなど共有のエージェントに接続した場合、そのエージェントを使う全員がこのアカウントのメールアドレスを見られます。

引数：なし

## クレジット

### kafkai_get_credit_balance

現在の残高、累計の購入量と消費量、直近10件の取引を、呼び出しごとの内訳つきで返します。無料です。残高の確認でクレジットを消費することはありません。

クレジットの有効期間は付与日から90日で、古いものから消費されます。`expiring` には、未使用のクレジットが付与ごとに、利用できる最終日 `valid_until` とともに期限の近い順で並びます。残りをいつまでに使えばよいか、エージェントが伝えられます。

日付と時刻はすべてUTCで、`time_zone` がそれを示します。`valid_until` はUTCの日付です。`expires_at` はそのクレジットが使えなくなる正確な時刻で、`valid_until` の翌日の0:00（UTC）です。日本時間では同じ日の9:00にあたります。エージェントに頼めば、`expires_at` を現地の時刻に直せます。

引数：なし

## プロンプト

Kafkai MCPサーバーは、ツールに加えてプロンプトを提供します。プロンプトは、エージェントが最初から最後まで実行する、用意済みの手順書です。MCPのプロンプトに対応したクライアントでは、プロンプトまたはスラッシュコマンドのメニューに表示されます。プロンプトを選択すると、手順書の内容がエージェントに渡されます。プロンプト自体は無料です。エージェントがその後呼び出すツールには、通常どおりの料金がかかります。手順書は、開始前に合計の料金を伝えるようエージェントに指示します。

| プロンプト | 内容 | ページ |
|---|---|---|
| `kafkai_weekly_seo_plan` | 週次の確認です。順位の変動、検索結果の1ページ目、次に書くキーワード、被リンク、Search Consoleの改善点を確認し、施策を3つ提案します。 | [プレイブック：週次SEOプラン](https://kafkai.com/ja/docs/weekly-seo-plan/) |
| `kafkai_help` | Kafkaiの使い方についての質問に、最新のドキュメントを読んで回答します。 | [AIエージェント用Kafkaiヘルプ](https://kafkai.com/ja/docs/kafkai-help/) |

引数：

- `language`：手順書の言語。`en`（デフォルト）または `ja` を指定します。どちらを指定しても、エージェントはお客様が書いた言語で返答します。

各プロンプトの内容は、対応するページと同じです。クライアントがプロンプトを一覧表示しない場合は、ページの先頭にある1行をエージェントに貼り付けるか、ページのスキルファイルを導入します。
