> ## 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.

# Visibility の推移

> 1 つのアセットについて、日次・週次・月次の Visibility 折れ線グラフを作成します

Profound アプリの各 Visibility タイルに表示される折れ線グラフは、`date`
ディメンションを追加した 1 回の呼び出しで取得できます。`date_interval` を使用して、
日・週・月の集計単位を切り替えます。

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

## この例の仕組み

1. **dimensions に `date` を追加し、`date_interval` を設定します**(`"day"` / `"week"`
   / `"month"`)。集計単位ごとに 1 行が返されます。集計単位のサイズが異なると、
   数値も異なります。[Headline + daily](/ja-jp/cookbook/visibility/headline-and-daily) を参照してください。
2. **アセットでフィルタリング**し、各集計単位が 1 行になるようにします。
3. **位置はハードコードせず、`info.query` から読み取ります**。

<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
  DATE_INTERVAL = "day"          # or "week" / "month"


  def get_visibility_over_time(category_id, asset_name, start_date, end_date, interval="day"):
      """Daily/weekly/monthly Visibility Score for one asset, sorted by date."""
      res = client.reports.visibility(
          category_id=category_id,
          start_date=start_date,
          end_date=end_date,
          metrics=["visibility_score"],
          dimensions=["date"],
          date_interval=interval,
          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
      ]
      points.sort(key=lambda p: p[0])
      return points   # → [("2026-05-05", 0.78), ("2026-05-06", 0.81), ...]


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

  points = get_visibility_over_time(category_id, asset_name, START_DATE, END_DATE, DATE_INTERVAL)
  for date, score in points:
      print(f"{date}  {score:.1%}")
  ```

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

  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>

## 集計単位の切り替え

`date_interval` を変更すると、データをより粗い単位で集計できます。

| `date_interval` | 取得される内容 |
| - | - |
| `"day"` | 暦日(米国東部時間)ごとに 1 ポイント |
| `"week"` | 週ごとに 1 ポイント(週の始まりは日曜日) |
| `"month"` | 暦月ごとに 1 ポイント |

API は `"hour"`、`"quarter"`、`"year"`、`"relative_week"`(`start_date`
から数えた週)も受け付けます。同じ期間であれば、返される行数は集計単位の
サイズに応じて変わります。