FactCheck は同じ
{ info, data } エンベロープを使用しますが、カテゴリ単位 (
scope/assets/metrics パラメータなし) で、より限定的な filter を受け付けます。
単一フィールドのリーフをトップレベルの and で結合したもので、否定できるのは topic のみです。詳細は
各ページを参照してください。すべての v2 エンドポイントは、フィルタが値を受け取る箇所で 名前または UUID を受け付けます。
UUID は
GET /v1/org/models、/v1/org/regions、/v1/org/personas、
/v1/org/assets、/v1/org/categories、およびカテゴリごとの
…/topics、…/tags、…/prompts エンドポイントから取得できます。共通のリクエストフィールド
グループ化
group_by は、1 つの集計行を値ごとの 1 行に変換します。グループ化した各フィールドは
行にエコーされます。
- 時系列を取得するには、
date(およびinterval) でグループ化します。 - 日付以外 のディメンションでグループ化した場合、行には
rankが含まれます。 - 利用可能なディメンションはレポートによって異なります。各エンドポイントのリファレンスを参照してください。
指標
必要な指標をリクエストすると、各行の 名前付きフィールド として返されます (位置ベースの配列やinfo.query の参照は不要です)。
スコープとアセットの選択
scope:ownedは自社所有のアセット/ドメインに限定し、allはすべてを対象にランク付けします。- 可視性のみ: 別の
assetsパラメータでアセットを選択します。名前 (is)、リスト (in。scopeより優先されます)、または{ op, value }を指定します。 選択した場合は一致するものがすべて返され、limitは無視されます。 - センチメント では
assetが必須です (センチメントはブランド単位のため)。
フィルタ
filter は 最大深さ 3 の再帰的なツリーで、YouTube ソーシャルレポートを含む
すべてのレポートで使用できます。
{ "and": [ … ] }、{ "or": [ … ] }、{ "not": <node> }、および
リーフ { "field", "op", "value" }。
演算子
value は単一の値、または in / not_in の場合はリストです。名前 または UUID を指定できます。
contains / matches は名前に対して一致します。
2 つのフィルタレイヤー
フィールドは 2 つのレイヤーに分かれます。これらはand で組み合わせます。or/not では
レイヤーを混在させられません (混在させると 422 が返されます)。
プロンプトレイヤー (完全なツリー、すべての演算子):
model、topic、region、persona、prompt、tag。
エンティティ / 引用レイヤー (トップレベルの and リーフのみ、レポートによって異なります):
引用では、ドメインレポートでは
domain で、group_by: ["page"] を指定した場合は
page でフィルタリングします。それぞれが自身のレポートのエンティティをフィルタリングします。source: "citation" のセンチメントは常にページの行を返し、group_by を
サポートしません。カウント対象の引用を絞り込むにはプロンプトレイヤーのフィルタを使用し、
返されるページを絞り込むには citation_category または page を使用してください。YouTube レポートでは
channel エンティティフィルタを使用します。and を使用して
プロンプトレベルのフィルタと組み合わせることはできますが、or や not の下で組み合わせることはできません。
YouTube の domain および page フィルタは、近似されるのではなく拒否されます。カテゴリの引用タグの一覧は Get Citation Tags で取得できます。
必要なタグはすべて 1 つの
in リーフにまとめてください (値は OR で結合されます)。2 つの
別々の citation_tag リーフを AND で結合したり、空のリストを渡したりすると 422 が返されます。並べ替え
サポートされている場合、sort は { "field": "<metric>", "dir": "asc" | "desc" } です。
フィールドは、リクエストした並べ替え可能な指標 (日付でグループ化した場合は date) である必要があります。
引用には sort がありません: 常に引用数の多い順にランク付けされます。
ページネーション
レスポンスはlimit 件の行と info.next_cursor を返します。次のページを取得するには、そのトークンを
cursor として渡します。最後のページでは next_cursor は null になります。
ストリーミング
YouTube ソーシャルレポートを除くすべてのレポートエンドポイントには、/stream バリアント
(Server-Sent Events) があります。まず summary イベント (info ブロック) が送信され、続いて行ごとに 1 つの result
イベントが送信されます。limit/cursor は無視され、デフォルトではすべての結果が返されます。
上限を設けるには max_results を指定します。センチメントのストリーミングは、ページ分割エンドポイントと同じ
ソース固有の行形式で、source: "response" と source: "citation" の両方を
受け付けます。
レスポンス形式
すべてのレポートは{ info, data } を返します。
info には解決されたクエリ (対象範囲のモデル、適用されたフィルタ、日付、
ページネーション) がエコーされます。data は行で、指標は名前付きフィールドとして、
group_by のディメンションが付加された状態で含まれます。