GEOモニタリングAPI: ブランドの言及と引用

​

モニターとは

• 回答テキストにブランドのエイリアスが現れるかとその文字オフセット、回答が登録済みの自社ドメインのいずれかを 引用したか、設定した競合のどれが同じ回答に現れたかを記録します。
• 感情スコアや市場シェアの推定値は生成しません。順位は、回答が挙げたブランドの中での位置であり、下のカテゴリ モニターのブランドランキングがその例です。

​

競合は自動で見つけます

• 見つけた競合は source: "auto"、自分で追加した競合は source: "user" です。自分で追加したものを読み取りが変更したり 削除したりすることはありません。
• 見つけた一覧が変わると、モニターに保存された回答を新しい一覧で数え直します。そのため、レポート内のすべてのブランドは 同じ回答をもとに測定されます。最後の読み取り時刻はモニターの competitorsReadAt にあります。
• ラテン文字の名前は単語単位で一致させます。たとえば「replicates」はブランド Replicate の言及として数えません。

​

モニターセットは意図をもって分ける

• トピックと市場ごとに1つのモニターにして、レポートのコホートを比較可能に保ちます。「おすすめのCRM」と 「CRMの価格はどう決めるか」を1つのセットに混ぜると、異なる2つの意図が1つの数字に平均されます。
• プロンプトは購入者の言い回しで書き、自社ブランドを決して含めないでください。ブランドを含むプロンプトは常に 言及と判定され、永遠に100%を報告して何も測りません。競合名は問題なく、最も有用なプロンプトになることも 多いです。

​

カテゴリモニター: 市場のブランドを順位付けする

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'

​

レポートが順位付けするもの

• rank は、ブランドを挙げた回答の数で順序付けします。これらの回答が挙げたブランドの中での位置です。どの回答にも 挙げられなかったブランドの rank は null です。
• ブランドの mentionRate は、そのブランド自身の sampleSize(ブランドが一覧にあった間に採点された回答)で割ります。 今日追加したブランドは今日から測定されます。
• shareOfVoice は期間内の 100 × そのブランドの言及数 / 追跡ブランドの言及の合計 なので、ひとつの期間のシェアを 足すと100になります。
• GET /v1/monitors はカテゴリモニターごとに leader(最も多く挙げられたブランドとその割合)を加えます。mentioned と cited は常に 0 です。
• GET /v1/monitors/{id}/answers/{taskId} は mode、空の aliases、追跡ブランドの一覧である competitors を返します。

​

検索需要からプロンプトをリサーチする

curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'

​

コストとスケジュール

credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours

• 実行は一度に集中しません。タスクはプランの同時実行数とキューが許す分だけ投入されるため、無料プランの上限を 超える実行は破棄されず数分かけて届きます。進行中の実行はレポートの health.pending で確認してください。
• 次の期間は保証ではなく時刻です。nextRunAt は実行の予定時刻で、1週間一時停止したモニターは逃した実行を まとめて行わず、再開した時点から1間隔後に再開します。

​

エンドポイント

​

モニターを作成する

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'

​

実行してからレポートを読む

​

数字の意味

• 期間、エンジン別グループ、セル別グループの mentionRate は 100 × 言及された回答 / 採点された回答 です。 エンジン別比率の平均ではなく回答数で重み付けするため、忙しいエンジンが静かなエンジンに埋もれません。 (ブランド自身の比率は独自の分母を持ちます。次で説明します。)
• citationRate は、登録済みの自社ドメインのいずれかを引用した回答について同じ形で数えます。ドメインを登録 していなければ引用追跡がオフなので、常にゼロです。
• ブランドの比率は期間全体ではなく自身の sampleSize で割ります。 自社ブランドは採点されたすべての回答、 競合はモニターに登録されていた間に採点された回答だけです。今日競合を追加すると、最初のレポートはその競合を 測った回答だけを扱い、存在前の履歴は不利に数えません。該当する回答がないブランドは0%ではなく mentionRate: null を報告します。0%は実際に消えたように読めてしまうからです。
• brands の shareOfVoice は、期間内の 100 × そのブランドの言及 / 追跡中の全ブランドの言及 で、1つの期間の シェアを合計すると100になります。これらのプロンプトで収集した回答の中でブランドを比較する値であり、 市場シェアでも可視性ランキングでもありません。レガシー詳細エンドポイントの shareOfVoice は以前の回答浸透率の 見方で、各ブランドを収集した回答数に対して数えるため合計が100を超えることがあります。2つを1つのチャートに 混ぜないでください。
• competitorOnly(と opportunities リスト)は、自社ブランドがなく設定済みの競合を挙げた回答を数えます。 実際に手を打てるギャップです。
• 比率はゼロではなくnullになり得ます。 期間に回答がなければ null、比率ゼロは回答があったが1つも一致 しなかったことを意味します。
• 回答なしで完了した観測は「言及なし」として数えます。 分母に残り、quality.noAnswerObservations がその数を 示します。失敗したタスクはすべての比率から除外され health にのみ現れます。壊れたエンジンは黙って不在に 変わるのではなくサンプルを減らし、quality がそれを不在として再構成することもありません (historicalFailures は常に null)。
• 誤解を招く変化量は保留します。 一方の期間に回答がない場合(insufficient_periods)、採点コンテキストが できる前に採点された行の場合(legacy_scoring_unknown)、2つの期間の間で採点定義が変わった場合 (scoring_definitions_changed)は、changes とセル別の mentionRateChangePp が null になり、 quality.comparable は false です。過去の行は採点時の定義を保持するため(quality.scoring)、エイリアスや 競合を変えても過去が書き換わることはありません。例外は上で説明した毎月の競合読み取りだけです。
• サンプルサイズを公開します。 採点された回答が30未満なら quality.lowSample がtrueになり、 quality.missingCells はまだ回答のない設定済みのプロンプト × エンジンのセル数を数え、quality.partialDays は 期間が半分に切ったUTCの日を示します。部分日の件数が少ないのは計算上の結果であり、減少ではありません。

​

回答のソース

​

引用の推移

curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

​

採点済みの行をエクスポートする

​

数字の裏にある回答を読む

• answerText: エンジンが返したままの回答。可能ならmarkdownで、最大8,000文字、それより長い場合は末尾に 省略記号を付けて切り詰めます。
• sources: エンジンの順序での引用。それぞれラベルと、引用リスト内での1始まりの位置を持ちます。
• aliases と competitors: この行の照合対象。言及を鵜呑みにせず確認できます。
• scoringContext: 使われた定義そのもの。version ハッシュ、採点時刻、answerPresent、上のテキストが 切り詰められた場合の evidenceTruncated を含みます。

​

この領域のエラー

​

エージェントと組み合わせる

1. GET /v1/monitors/capabilities: 何かを消費する前に、エンジン、価格、上限を読みます。
2. GET /v1/monitors: そのトピックと市場の既存モニターを再利用するか、POST /v1/monitors で作成します(先に POST /v1/monitors/suggest を呼んで候補を編集しても構いません)。
3. POST /v1/monitors/{id}/run: 次の予定期間より前に回答が必要なら実行します。
4. GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT: まず quality(comparable、lowSample、 missingCells、partialDays)を読み、それから数字を見ます。health.pending が落ち着き、 quality.sampleSize が増えなくなるまでポーリングします。
5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: nextCursor でページをめくり、プロンプトを勝ち取って いるページを見つけます。
6. GET /v1/monitors/{id}/answers/{taskId}: 何かを決める前に、opportunities の先頭項目の裏にある回答を開きます。
7. GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv: 同じ期間をエクスポートし、 x-next-cursor が空になるまでたどります。

​

上限