> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 1 つのアセットの Visibility Score

> 期間内のアセットのトラフィック加重 Visibility Score と、前の期間からの変化を取得します

Profound アプリの各 Visibility タイルに表示されるヘッドラインの数値と、
その横にある `+1.0%` の変化バッジです。同じ呼び出しを 2 回(現在の期間と
同じ長さの前の期間)実行し、2 つのスコアの差を求めます。

## この例の仕組み

1. **時系列ではなく集計。** `dimensions` から `date` を省略し、
   `asset_name` でフィルタリングします。レスポンスは、トラフィックで重み付けされた
   単一のスコアを含む 1 行です。
2. **同じ呼び出しを 2 回実行し**(現在の期間に 1 回、同じ長さの
   前の期間に 1 回)、差を求めます。
3. **位置は `info.query.metrics` から読み取ります。** 配列のインデックスを
   ハードコードしないでください。

<RequestExample>
  ```python Python theme={null}
  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)")
  ```

  ```bash curl theme={null}
  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>"}]
    }'
  ```
</RequestExample>

## 利用可能なメトリクス

`visibility_score` を以下のいずれかに置き換えると、別の KPI タイルを取得できます。

| メトリクス | 説明 | 形式 | 方向 |
| - | - | - | - |
| `visibility_score` | アセットが登場した回答の割合 | パーセント | 高いほど良い |
| `share_of_voice` | 全言及のうちアセットが占める割合 | パーセント | 高いほど良い |
| `average_position` | アセットが言及されたときの平均順位 | 順位 | **低い**ほど良い |
| `mentions_count` | 言及の生の件数 | 数値 | 高いほど良い |
| `executions` | 実行されたプロンプトの数 | 数値 | 高いほど良い |

`average_position` の場合は、差分の色のロジックを反転させてください。負の `delta`
は改善を意味します。

## よくある次のステップ

<CardGroup cols={2}>
  <Card title="同じメトリクスの推移をプロットする" icon="chart-line" href="/ja-jp/cookbook/visibility/visibility-over-time">
    dimensions に `date` を追加して、日次の折れ線グラフを作成します。
  </Card>

  <Card title="ヘッドラインと日次系列を同時に" icon="layer-group" href="/ja-jp/cookbook/visibility/headline-and-daily">
    ヘッドラインの呼び出しとチャートの呼び出しが異なる数値を返す理由。
  </Card>
</CardGroup>