> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Citation Analysis > プロンプト単位のAI可視性診断: エンジンが実行した検索、取得・引用したページ、回答が挙げるブランドとその背後のページ、自社ブランドの位置、優先順位付きのアクション 完了したAI回答を、その背後にあるページと比較します。結果には、エンジンが実行した検索、取得したページと引用したページ、 回答が挙げるブランドとそれを挙げているページ、自社ブランドの位置、優先順位付きのアクションが含まれます。さらに、 引用された各ページの段落を対応する回答の部分に結び付けてリンクごとに説明を付け、引用ページに共通する点をまとめます。 これは既存の回答に対する事後的な対応分析です。ソースがモデルに文を生成させた証拠でも、ページの品質スコアでも ありません。判定ではなく、確認するための根拠として扱ってください。 ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/citation-analysis \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "answer": "…the AI answer, as raw markdown…", "prompt": "best password manager for a small team", "engine": "CHATGPT", "brand": "1Password", "competitors": ["Bitwarden"], "citations": [ { "url": "https://example.com/best-password-managers", "body": "…the page markdown…" }, { "url": "https://another.example.com/pricing" } ] }' ``` `GET /v1/async/task/:id` をポーリングするか、送信時に `webhook.url` を指定してください。タスクは `taskType: "CITATION_ANALYSIS"` として報告されます。この分析は `POST /v1/async/task` ではなく専用エンドポイントで 送信してください。GEO Audit 時代を含む旧エンドポイント `POST /v1/geo-audit`、`POST /v1/source-influence` と `POST /v1/research`、タスク種別 `GEO_AUDIT`、`SOURCE_INFLUENCE` と `CITATION_ATTRIBUTION`、`include.geoAudit`、`include.sourceInfluence` も引き続き使えます。レスポンスは常に新しい名前を使います。 ### 実行済みのタスクを分析する 回答がこのAPIから得たものなら、結果から回答と引用をコピーする代わりにタスクidを送ってください。 ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/citation-analysis \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "taskId": "7c1f…", "brand": "1Password", "competitors": ["Bitwarden"] }' ``` タスクは自分のもので、`COMPLETED` であり、`GET /v1/async/task/:id` でまだ読める必要があります。回答の Markdown(エンジンがMarkdownを返さなかった場合はテキスト)が `answer` になり、引用URLがエンジンの順序で `citations` になります。最初の100件までで、ディスカッションスレッドは最大10件です。商品・動画カードの プレースホルダー(`googleusercontent.com` のリンク)と Google 検索のリンクは、読むページがないためスキップします。 送らなければタスクの `prompt`、`country`、エンジンを使います。`taskId` を `answer` や `citations` と一緒に送ると `400` で拒否され、未完了のタスクや回答テキスト・引用URLのないタスクも同様です。不明または期限切れのタスクidは `404` を返します。 ### 収集と同時にすべての回答を分析する 収集リクエストに `include.citationAnalysis: true` を加えると、回答が収集された直後に分析が実行されます。 回答エンジン(`CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE_AIO`, `GOOGLE_AIMODE`, `NAVER_AI_BRIEF`, `NAVER_AI_TAB`, `BING_SEARCH`, `BING_COPILOT`)で、単一タスク、タスクバッチ、グリッド、`POST /v1/batches` のいずれでも使えます。 ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/async/task \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "taskType": "CHATGPT", "payload": { "prompt": "best password manager for a small team", "country": "US", "include": { "citationAnalysis": true } }, "webhook": { "url": "https://example.com/hook" } }' ``` 分析は上の `taskId` と同じ方法で回答と引用 URL を読み取ります。回答の結果には `response.citationAnalysis` が入ります。`GET /v1/async/task/:id` が返す分析タスクそのもので、`task`、`credits`、そして `response` または `error` を含みます。 * **Webhook**: 分析の完了後、回答と分析をまとめて一度だけ送ります。 * **ポーリング**: 回答タスクは回答の準備ができた時点で `COMPLETED` になります。`response.citationAnalysis.task.status` が `COMPLETED` か `FAILED` になるまでポーリングを続けてください。 * **バッチ**は、すべての回答とその分析が終わった時点で完了します。 * **分析がない場合**: 回答に読み取れる引用 URL がない場合や、クレジットまたはキーの1日の上限で分析の hold を確保できない場合、`response.citationAnalysis` は `{ "error": "…" }` となり、回答はすぐに届きます。 * **課金**: 分析は他のCitation Analysisタスクと同じく使用量に応じて別に課金されます。回答の課金額は変わりません。特定のタスクタイプだけを許可したキーでは `CITATION_ANALYSIS` も許可する必要があります。 ## Payload | フィールド | 必須 | 説明 | | - | - | - | | `taskId` | `answer` + `citations` の代わり | 自分の完了した回答タスク。上記を参照。 | | `answer` | はい(`taskId` がない場合) | 元の回答Markdown、1–200,000文字。変更しないでください。すべての範囲はまさにこのテキストのUTF-16オフセットです。 | | `citations[]` | はい(`taskId` がない場合) | エンジンが引用したページと、任意で取得したが引用しなかったページ。引用は最大100件、非引用は最大50件、引用は最低1件、ディスカッションスレッドのURLは最大10件。 | | `citations[].url` | はい | HTTP(S) URL、最大2,048文字。 | | `citations[].body` | いいえ | ソースのMarkdown、引用ごとに最大300,000文字、リクエスト本文全体で最大1 MiB。渡した本文はそのまま分析し、新たに取得した内容で置き換えません。本文がなければページを取得し、読めなかったページはそのソースに `error` として報告します。 | | `citations[].kind` | いいえ | `inline` または `panel`。省略時は回答内のリンクから判定します。 | | `citations[].cited` | いいえ | 既定値 `true`。`false` はエンジンが取得した(検索結果)が引用しなかったページを示します。 | | `citations[].position` | いいえ | 1以上の整数。検索結果におけるそのページのエンジン自身の順位。 | | `citations[].query` | いいえ | そのページを見つけた検索(500文字以内)。`queries` になければ追加されます。 | | `citations[].citedText[]` | いいえ | エンジン自身が引用したと報告した箇所を最大20件(各2,000文字以内)。 | | `citations[].publishedAt` | いいえ | エンジンが報告した公開日、64文字以内。 | | `queries[]` | いいえ | エンジンが実行した検索を最大20件、各500文字以内。 | | `prompt` | いいえ | 元の質問。 | | `engine` | いいえ | 回答を生成したAIエンジン。 | | `brand` | いいえ | 自社ブランド名。指定すると結果に `visibility` と `actions` が加わります。 | | `brandDomains[]` | いいえ | `coway.com` のような自社ブランドのサイトのホスト名を最大10件。スキームやパスを含まない、英数字・ドット・ハイフンからなる253文字以内のホスト名のみ指定できます。`brand` が必要で、`brand` なしで送るとリクエストは `422` で拒否されます。`brandDomains` を指定しない場合、ホスト名にブランド名を含むホストを自社サイトと見なします。 | | `brandAliases[]` | いいえ | 自社ブランドの別名(製品ライン、現地表記)を最大10件、各200文字以内。`brand` が必要で、`brand` なしで送るとリクエストは `422` で拒否されます。 | | `competitors[]` | いいえ | 競合名を最大25件。`brands` にロール `competitor` として報告されます。 | | `country` | いいえ | ソースを取得する国、既定値 `US`。 | `taskId` または `include.citationAnalysis` を使うと、これらのフィールドは回答の生データから埋められます。`CHATGPT` では、エンジンの検索が `queries` になり、取得されたすべてのページが `cited`、`position`、`citedText`、 `publishedAt`、`query` 付きの引用になります。トラッキングパラメータだけが異なる同じURLは統合されます。Google AI Overview では、オーバービューのソースが引用、それ以外のオーガニック結果が非引用となり、`position` にはオーガニック 順位が入ります。その他のエンジンは引用ソースのみを提供します。 > [!WARNING] > > リクエストに `analysis` を送ると `400` で拒否されます。インサイトはすべての結果に含まれます。 ## 結果 v4 より前に保存された結果は、`version` フィールドのない以前の形のままです。 ```json theme={"theme":"css-variables"} { "version": 4, "answer": "For most homes, the Coway Airmega 250 is the best all-round pick. Levoit Core 300 is a strong budget choice, and Blueair Blue Pure 211+ suits large rooms.", "queries": [ { "id": "q0", "text": "best air purifiers 2026 reviews", "sourceIds": ["s0", "s1", "s2"] } ], "sources": [ { "id": "s0", "url": "https://www.example-reviews.com/best-air-purifiers", "domain": "example-reviews.com", "channel": "editorial", "cited": true, "position": 1, "queryIds": ["q0"], "publishedAt": "October 7, 2026", "citedText": ["Levoit Core 300 is the best budget purifier we tested."], "brandIds": ["b1", "b2"], "own": false, "paragraphs": [ { "id": "s0p0", "text": "Levoit Core 300 is the best budget purifier we tested." }, { "id": "s0p1", "text": "For large rooms, the Blueair Blue Pure 211+ cleared the air fastest." } ] }, { "id": "s1", "url": "https://www.coway.com/airmega-250", "domain": "coway.com", "channel": "own", "cited": false, "position": 4, "queryIds": ["q0"], "publishedAt": null, "citedText": [], "brandIds": ["b0"], "own": true, "paragraphs": [] }, { "id": "s2", "url": "https://www.reddit.com/r/AirPurifiers/comments/abc123/budget_pick", "domain": "reddit.com", "channel": "community", "cited": true, "position": 6, "queryIds": ["q0"], "publishedAt": null, "citedText": [], "brandIds": ["b1"], "own": false, "paragraphs": [ { "id": "s2p0", "text": "Two years with the Levoit Core 300 and it is still quiet on sleep mode." } ] } ], "brands": [ { "id": "b0", "name": "Coway", "role": "target", "rank": 1, "answerRanges": [{ "start": 20, "end": 25 }], "citedSourceIds": [], "retrievedSourceIds": ["s1"], "ownSourceIds": ["s1"] }, { "id": "b1", "name": "Levoit", "role": "competitor", "rank": 2, "answerRanges": [{ "start": 66, "end": 72 }], "citedSourceIds": ["s0", "s2"], "retrievedSourceIds": [], "ownSourceIds": [] }, { "id": "b2", "name": "Blueair", "role": "answer", "rank": 3, "answerRanges": [{ "start": 113, "end": 120 }], "citedSourceIds": ["s0"], "retrievedSourceIds": [], "ownSourceIds": [] } ], "links": [ { "id": "l0", "paragraphId": "s0p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Names the Levoit Core 300 as the budget pick." }, { "id": "l1", "paragraphId": "s0p1", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Recommends the Blueair Blue Pure 211+ for large rooms." }, { "id": "l2", "paragraphId": "s2p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Reports long-term use of the Levoit Core 300." } ], "visibility": { "brandId": "b0", "stage": "mentioned", "rank": 1, "answerBrands": 3 }, "actions": [ { "id": "a0", "type": "improve_page", "control": "owned", "priority": 1, "summary": "Coway's Airmega 250 page was retrieved for this search but not cited.", "steps": [ "Add a table of room coverage, noise level and yearly filter cost, the criteria the cited review compares.", "Show when the specifications were last updated." ], "sourceIds": ["s1"], "brandIds": ["b0"], "queryIds": ["q0"], "linkIds": [] }, { "id": "a1", "type": "publish_page", "control": "owned", "priority": 2, "summary": "No Coway page was cited for this search; the cited review is a dated buying guide.", "steps": [ "Publish a 2026 air purifier buying guide on coway.com, organized by room size and budget.", "Explain how models were compared, show measured results, and name the author and date." ], "sourceIds": ["s0"], "brandIds": ["b0"], "queryIds": ["q0"], "linkIds": ["l0", "l1"] }, { "id": "a2", "type": "post_on_platform", "control": "platform", "priority": 3, "summary": "A cited Reddit thread recommends Levoit and never mentions Coway.", "steps": [ "Reply as an identified Coway representative with the Airmega 250 details the thread asks about." ], "sourceIds": ["s2"], "brandIds": ["b1"], "queryIds": ["q0"], "linkIds": ["l2"] }, { "id": "a3", "type": "pitch_publisher", "control": "outreach", "priority": 4, "summary": "The top cited review names Levoit and Blueair but not Coway; only its publisher can add the Airmega 250.", "steps": [ "Offer the editors an Airmega 250 for testing.", "Send test data for the criteria the review uses: room coverage, noise and filter cost." ], "sourceIds": ["s0"], "brandIds": ["b1", "b2"], "queryIds": ["q0"], "linkIds": ["l0", "l1"] } ], "insights": [ { "summary": "Both cited pages recommend Levoit for a budget; the review also backs Blueair for large rooms.", "sourceIds": ["s0", "s2"], "linkIds": ["l0", "l1", "l2"] }, { "summary": "The answer names Coway first, yet no cited page names it; only its own page, which was not cited, does.", "sourceIds": ["s1"], "linkIds": [] } ] } ``` ### `version` この形では常に `4` です。 ### `answer` 送信した回答をそのまま返します。`answerRanges` はまさにこの文字列のオフセットです。JavaScript のUTF-16コード 単位で、`start` は含み、`end` は含みません。テキストを分割し直さず、`answer.slice(start, end)` のようにそのまま 切り出してください。`links[]` の範囲は回答の意味的なまとまり(文、リスト項目、表のセル)を丸ごと指し、 `brands[]` の範囲は書かれたとおりの名前を指します。境界は元のテキスト基準です。 ### `queries[]` この回答のためにエンジンが実行した検索です。それぞれ `id`、`text`、そしてその検索が見つけたソースを示す `sourceIds` を持ちます。エンジンが検索を公開せず、送信もしなかった場合は空です。 ### `sources[]`: ページごとに1エントリ * `id`: 不透明な識別子。結果内で一意です。 * `url`: ページのURL。`domain`: そのホスト。 * `channel`: ページを管理する主体。ホストから判定します: * `own`: 自社ブランドのサイト(`own` が `true` のときに限る)。 * `brand`: 結果が挙げる他ブランドの自社サイト。 * `editorial`: 発行元。ページを変更できるのは発行元だけです。認識できないホストは `editorial` として 報告されます。 * `retailer`: オンラインストアまたはマーケットプレイス。 * `review_platform`: 顧客レビューまたは企業レビューのサイト。 * `community`: フォーラムまたはQ\&Aサイト。 * `video`: 動画プラットフォーム。 * `social`: ソーシャルネットワーク。 * `blog_platform`: ホスティング型のブログサービス。 * `reference`: 百科事典またはwiki。アクションの対象にはなりません。 * `cited`: 回答がページを引用していれば `true`、エンジンが取得しただけなら `false`。 * `position`: そのページのエンジン自身の順位。順位がなければ `null`。 * `queryIds[]`: そのページを見つけた検索。 * `publishedAt`: エンジンが報告した公開日、または `null`。 * `citedText[]`: エンジン自身が引用したと報告した箇所。なければ `[]`。 * `brandIds[]`: 読み取れたページ本文、タイトル、`citedText` に登場するブランド。 * `own`: ページが自社ブランドのサイト上にあれば `true`。 * `paragraphs[]`: 結果に含まれた引用ページの段落。それぞれ `id`(結果全体で一意)と段落の `text` を持ちます。 リンクなしで含まれる段落もあります。非引用ページでは常に空です。 * `error`: ページを読めなかった場合のみ存在します。このとき `paragraphs` は空で、文字列はそのソースに関する 短い理由です。 ### `brands[]` 結果が追跡するすべてのブランド: 自社の `brand`(`role: "target"`)、`competitors`(`"competitor"`)、そして回答が 挙げるその他のブランド(`"answer"`)。 * `rank`: 回答でそのブランド名が初めて現れる順、1から。回答がそのブランドを挙げていなければ `null`。 * `answerRanges[]`: 回答がそのブランドまたはその製品名を挙げている正確な箇所。同じUTF-16オフセットで、`answer.slice(start, end)` は書かれたとおりの名前を返します。大文字小文字を区別せず単語単位で照合し(空白で区切らない文字体系を除く)、見出しや表のセルも対象ですが、リンクURLや画像マークアップの中は対象外です。`links[]` の範囲と違い、回答のまとまり全体ではありません。 * `citedSourceIds[]`: ページがそのブランドを挙げている引用ソース。 * `retrievedSourceIds[]`: ページがそのブランドを挙げている非引用ソース。 * `ownSourceIds[]`: そのブランド自身のサイト上のソース。target のみ埋められます。 ### `links[]`: 段落ごとに1つの関係 * `paragraphId`: このリンクが対象とする段落。常に `sources[]` に存在する段落を指します。 * `answerRanges[]`: この段落に対応する回答の部分で、上と同じUTF-16オフセットの `start`/`end` ペアです。1つの リンクが複数の範囲を持つことがあり、同じ回答テキストが範囲間で重複することはありません。各範囲は回答の まとまり(文、リスト項目、表のセル)を丸ごと指します。 * `explanation`: 対応を説明する短い文。段落が回答のその部分について何を述べているかを記します。 ### `visibility` この回答における自社ブランドの位置です。`brand` を送らなかった場合は `null`。 * `brandId`: `brands[]` 内の自社ブランド。 * `stage`: 次のいずれか: * `mentioned`: 回答が自社ブランドを挙げている。 * `on_cited_page`: 回答は挙げていないが、引用ページが挙げている。 * `on_retrieved_page`: エンジンが引用せずに取得したページだけが挙げている。 * `not_found`: 読み取ったどのページも挙げていない。 * `rank`: `brands[]` における自社ブランドの `rank`。 * `answerBrands`: 回答が挙げるブランドの数。 ### `actions[]` 自社ブランドのための優先順位付きの次のステップです。`brand` を送らなかった場合は `[]`。`priority` は1(最優先) から始まり、欠番はありません。アクションは `control` の順に並びます。まず自社が管理するもの(`owned`)、次に 自社が投稿できるプラットフォーム(`platform`)、最後にアウトリーチ(`outreach`)です。`summary` は1文、`steps[]` は 1〜5個の具体的なステップで、どちらも回答の言語で書かれます。`sourceIds`、`brandIds`、`queryIds`、`linkIds` は この結果内の根拠を指します。 | `type` | `control` | 表示される条件 | `sourceIds` | | - | - | - | - | | `improve_page` | `owned` | 自社サイトごとに1件: そのサイトの自社ページが取得されたが引用されなかった、または引用されたのに回答が自社ブランドを挙げていない。ステップは、引用ページと同じようにプロンプトに答えるために何を追加・変更すべきか(基準、数値、鮮度)を示します。 | そのサイトの自社ページ最大3件、引用されなかったページが先。 | | `publish_page` | `owned` | 自社ページがどれも引用されなかった検索について、引用ページを手本にした自社サイト上の新規ページの概要。ページの種類とタイトル、セクションと基準、示すべき根拠、日付、ブランドによる明確な執筆者表示を含みます。 | 手本にする引用ページ。 | | `post_on_platform` | `platform` | 小売、レビュープラットフォーム、コミュニティ、動画、ソーシャル、ブログプラットフォーム上のページが、競合ブランドを挙げているが自社は挙げていない。アクションは、自社アカウントでそのプラットフォームに出す自社の掲載、プロフィール、回答、投稿です。自社製品の掲載や改善、プロフィールの申請と実際の顧客へのレビュー依頼、ブランドの担当者であることを明示した回答、デモや比較の公開などです。プラットフォームやページの所有者に何かを依頼することはありません。ドメインごとに最大1件。 | そのプラットフォーム上の引用ページ(他者のページ)。 | | `pitch_publisher` | `outreach` | 引用された編集系ページが競合ブランドを挙げているが自社は挙げていない、または自社を挙げているのに回答は挙げていない。ページを変更できるのは発行元だけで、ステップは何を送るべきかを示します。 | 売り込むページ。 | `brandIds` は自社ブランド、またはそれらのページが挙げる競合ブランドを示します。アクションが、偽のレビューや 関係を明かさないレビュー、独立したレビュアーを装うこと、リンクの購入、自社が所有しないページの編集を提案する ことはありません。自社ブランドを挙げていても引用されなかった第三者ページは、アクションではなく `brands[].retrievedSourceIds` に示されます。 ### `insights[]` ページ全体から読み取れる内容の短い要約を最大4件示します。どのチャネルが引用されたか、引用ページに共通する形式・ 鮮度・基準、回答のブランドの順序が引用ページの扱う内容とどう対応するか、そして自社ブランドの位置です。 `sourceIds` は各要約の元になったページ、`linkIds` はリンクを示します。少なくとも一方は空でなく、この結果内の エントリしか指しません。インサイトは対応を説明するもので、助言ではありません。 ## 結果を正しく読む * **リンクがないことは判定ではありません。** リンクのない段落は回答の範囲と一致しなかっただけで、範囲のない 回答部分はリンクされた段落がなかっただけです。どちらもページが無関係、未使用、信頼できないという意味では ありません。 * **読めなかったページは不確かなままです。** `sources[].error` があれば、その引用は分析から除外されています。 リンクがないことを否定的な結果と見なさないでください。重要なら再試行するか `body` を渡してください。 * **対応であって因果ではありません。** 結果は、既存の回答と既存のページテキストが事後的にどう対応するか、そして それらのページがどのブランドを挙げているかを説明します。生成への影響を測ったり、ページを採点したり、回答の 生成過程を報告したりはしません。 * **`not_found` は読み取ったどのページにもないという意味です。** 自社ブランドがウェブ上に存在しないという意味では ありません。 * **取得データはエンジンに依存します。** 非引用ページは、エンジンが公開している場合(ChatGPT、Google AI Overview) か、`cited: false` のページを送った場合にのみ現れます。それ以外ではすべてのソースが引用となり、自社ページは 引用としてのみ現れます。 * **チャネルはホストから判定します。** `channel` はページのホストから推定したもので、誰が書いたかを読み取って 判定したものではありません。 * **アクションは提案であって保証ではありません。** この結果に挙げたページをもとに優先順位を付けたもので、実行しても 回答が変わるとは限りません。 * **idは内部用です。** `s…`/`q…`/`b…`/`l…`/`a…` の識別子を実行をまたいだ安定キーとして保存しないでください。 1つの結果の中でのみ有効です。 ## 実行と制限 * **サイズは失敗の理由になりません。** リクエスト契約が受け付けるもの、つまり最大200,000文字の `answer` と最大 100件の引用はすべて分析します。長い回答、多数のソース、非常に長いページは、拒否せずに処理を分割して扱います。 * **深さはページではなく回答に比例します。** 長いページだからといって、回答が裏付けられる以上のリンクは 生まれません。分析は回答に対応する可能性が最も高い箇所に集中し、対応があるすべてのソースが結果に表れます。 大きなページや、同じ記述をナビゲーション、一覧、レビューで繰り返すページでは、すべての出現ではなく最も強い 箇所を想定してください。 * **マークアップは根拠になりません。** サイトマップ、リンク索引、画像ギャラリーはリンクを生みません。それら だけでできたページは、対応を作り出さずに段落なしで報告されます。 * 読めなかったソースは、他に読めるソースがあればタスクを失敗させずに `sources[].error` で報告します。どの ソースも読めなかった場合、分析の失敗、タイムアウト、サービス設定エラーではタスクが失敗します。 * リクエストはAPIの他の部分と同様に使用量で計測します。送信レスポンスは一時的なクレジットの確保を示し、 最終的な課金はタスクが終了状態に達したときに確定します。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.