> ## 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 つのアセットについて期間スコアと日次の折れ線の両方を取得し、それぞれが別の呼び出しである理由を理解します

実際のダッシュボードのタイルには 2 つの数値が表示されます。**ヘッドラインの期間スコア**(1 つの
大きな数値)と**日次系列**(折れ線)です。これらは同じエンドポイントへの **2 回の
別々の呼び出し**から得られます。このレシピでは両方を並べて実行し、
それぞれの抽出方法と、一方から他方を導出できない理由を
説明します。

<Warning>
  **日次の行を平均して期間スコアを算出しないでください**：両者は計算方法が
  異なります。詳しくは [規約と注意点](/ja-jp/cookbook/setup/conventions#dont-average-daily-rows-to-get-a-period-score) を参照してください。
</Warning>

## この例の仕組み

1. **ヘッドラインの呼び出し**には `date` ディメンションがありません。API は期間全体について、
   トラフィックで重み付けされた単一のスコアを返します。
2. **系列の呼び出し**では、dimensions に `date` を追加し、`date_interval` を設定します。
   API は 1 日につき 1 行を返し、各行にはその日の重み付けされていない比率が含まれます。
3. **日次の値を平均してヘッドラインを計算しないでください。** ヘッドラインでは
   プロンプト数の多い日ほど大きく反映されますが、日次の平均はすべての日を
   等しく扱います。この 2 つは意図的に異なる方法で計算されています。

<RequestExample>
  ```python Python theme={null}
  import os
  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>"
  START_DATE    = "2026-05-05"
  END_DATE      = "2026-05-12"   # exclusive — returns data through 2026-05-11


  def get_headline_score(category_id, asset_name, start_date, end_date):
      """Traffic-weighted period score (no date dim)."""
      res = client.reports.visibility(
          category_id=category_id,
          start_date=start_date,
          end_date=end_date,
          metrics=["visibility_score"],
          filters=[{"field": "asset_name", "operator": "is", "value": asset_name}],
      )
      order = res.info.query["metrics"]
      return res.data[0].metrics[order.index("visibility_score")]


  def get_daily_series(category_id, asset_name, start_date, end_date):
      """One (date, score) point per day — for the line chart."""
      res = client.reports.visibility(
          category_id=category_id,
          start_date=start_date,
          end_date=end_date,
          metrics=["visibility_score"],
          dimensions=["date"],
          date_interval="day",
          filters=[{"field": "asset_name", "operator": "is", "value": asset_name}],
      )
      m_order = res.info.query["metrics"]
      d_order = res.info.query["dimensions"]
      i_score = m_order.index("visibility_score")
      i_date  = d_order.index("date")
      points = [
          (row.dimensions[i_date], row.metrics[i_score])
          for row in res.data
      ]
      return sorted(points, key=lambda p: p[0])


  # 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 calls.
  category_id = find_category_id(CATEGORY_NAME)
  asset_name  = find_asset_name(category_id, ASSET_NAME)

  headline_score = get_headline_score(category_id, asset_name, START_DATE, END_DATE)
  daily          = get_daily_series(category_id, asset_name, START_DATE, END_DATE)

  print(f"Headline: {headline_score:.1%}\n")
  print("Daily:")
  for date, score in daily:
      print(f"  {date}  {score:.1%}")
  ```

  ```bash curl theme={null}
  export PROFOUND_API_KEY=your_api_key_here

  # 1) Headline (no date dimension)
  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>"}]
    }'

  # 2) Daily series (add date dimension + date_interval)
  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"],
      "dimensions": ["date"],
      "date_interval": "day",
      "filters": [{"field": "asset_name", "operator": "is", "value": "<your-asset-name>"}]
    }'
  ```
</RequestExample>

## 2 つのレスポンスの違い

| | ヘッドラインの呼び出し | 系列の呼び出し |
| - | - | - |
| `dimensions` | `[]` | `["date"]` |
| `date_interval` | 送信しない | `"day"`(または week/month) |
| 返される行数 | 1 | N(バケットごとに 1 行) |
| 行ごとのスコア | 期間全体でトラフィック加重 | その日の中で重み付けなし |
| 用途 | 大きな KPI の数値 | チャートの折れ線 |

## 日次の値を平均できない理由

ヘッドラインは各日をプロンプト量で重み付けします。10,000 件の
プロンプトがある日は、100 件の日よりもヘッドラインを大きく動かします。日次の比率を平均すると、
この 2 日を同等に扱ってしまいます。ほとんどのアセットでは差は 1〜3 パーセンテージ
ポイントですが、トラフィックが急増するアセットではそれ以上になることがあります。ヘッドラインには
必ずヘッドラインの呼び出しを使用してください。