+1.0% の変化バッジです。同じ呼び出しを 2 回(現在の期間と
同じ長さの前の期間)実行し、2 つのスコアの差を求めます。
この例の仕組み
- 時系列ではなく集計。
dimensionsからdateを省略し、asset_nameでフィルタリングします。レスポンスは、トラフィックで重み付けされた 単一のスコアを含む 1 行です。 - 同じ呼び出しを 2 回実行し(現在の期間に 1 回、同じ長さの 前の期間に 1 回)、差を求めます。
- 位置は
info.query.metricsから読み取ります。 配列のインデックスを ハードコードしないでください。
import os
from datetime import date, timedelta
from profound import Profound
client = Profound(api_key=os.environ["PROFOUND_API_KEY"])
# What to fetch — replace with your own values.
CATEGORY_NAME = "<your-category-name>"
ASSET_NAME = "<your-asset-name>"
METRIC = "visibility_score" # or share_of_voice, average_position, ...
DAYS = 7
INCLUSIVE_END = date(2026, 5, 11) # the last day of your current window
def get_visibility_score(category_id, asset_name, metric, start, end):
"""Aggregate score for one asset in one window."""
res = client.reports.visibility(
category_id=category_id,
start_date=start.isoformat(),
end_date=end.isoformat(),
metrics=[metric],
filters=[{"field": "asset_name", "operator": "is", "value": asset_name}],
)
order = res.info.query["metrics"]
return res.data[0].metrics[order.index(metric)]
def current_and_prior_windows(inclusive_end, days):
"""Two (start, end_exclusive) pairs of equal length, back-to-back."""
current = (
inclusive_end - timedelta(days=days - 1),
inclusive_end + timedelta(days=1), # +1 day → exclusive end
)
prior = (current[0] - timedelta(days=days), current[0])
return current, prior
# Helpers — translate human-readable names into the IDs the report API needs.
def find_category_id(name):
"""Return the UUID of the category whose name matches (case-insensitive)."""
for c in client.organizations.categories.list():
if c.name.lower() == name.lower():
return c.id
raise ValueError(f"No category named {name!r}")
def find_asset_name(category_id, name):
"""Return the canonical asset name (case-insensitive) inside the category."""
for a in client.organizations.categories.assets(category_id):
if a.name.lower() == name.lower():
return a.name
raise ValueError(f"No asset named {name!r} in this category")
# Resolve names → IDs, then run both windows.
category_id = find_category_id(CATEGORY_NAME)
asset_name = find_asset_name(category_id, ASSET_NAME)
current, prior = current_and_prior_windows(INCLUSIVE_END, DAYS)
current_score = get_visibility_score(category_id, asset_name, METRIC, *current)
prior_score = get_visibility_score(category_id, asset_name, METRIC, *prior)
delta_pp = (current_score - prior_score) * 100
print(f"{asset_name} {METRIC}: {current_score:.1%} ({delta_pp:+.1f} pp vs prev period)")
export PROFOUND_API_KEY=your_api_key_here
# Current window
curl -X POST "https://api.tryprofound.com/v1/reports/visibility" \
-H "X-API-Key: $PROFOUND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category_id": "your-category-uuid",
"start_date": "2026-05-05",
"end_date": "2026-05-12",
"metrics": ["visibility_score"],
"filters": [{"field": "asset_name", "operator": "is", "value": "<your-asset-name>"}]
}'
# Previous window — same body, prior dates. Diff the two scores client-side.
curl -X POST "https://api.tryprofound.com/v1/reports/visibility" \
-H "X-API-Key: $PROFOUND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category_id": "your-category-uuid",
"start_date": "2026-04-28",
"end_date": "2026-05-05",
"metrics": ["visibility_score"],
"filters": [{"field": "asset_name", "operator": "is", "value": "<your-asset-name>"}]
}'
利用可能なメトリクス
visibility_score を以下のいずれかに置き換えると、別の KPI タイルを取得できます。
| メトリクス | 説明 | 形式 | 方向 |
|---|---|---|---|
visibility_score | アセットが登場した回答の割合 | パーセント | 高いほど良い |
share_of_voice | 全言及のうちアセットが占める割合 | パーセント | 高いほど良い |
average_position | アセットが言及されたときの平均順位 | 順位 | 低いほど良い |
mentions_count | 言及の生の件数 | 数値 | 高いほど良い |
executions | 実行されたプロンプトの数 | 数値 | 高いほど良い |
average_position の場合は、差分の色のロジックを反転させてください。負の delta
は改善を意味します。
よくある次のステップ
同じメトリクスの推移をプロットする
dimensions に
date を追加して、日次の折れ線グラフを作成します。ヘッドラインと日次系列を同時に
ヘッドラインの呼び出しとチャートの呼び出しが異なる数値を返す理由。