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

# レスポンス形式

> レポートのレスポンス構造とデータの解釈方法を理解する

## 概要

レポートエンドポイント（`/v1/reports/*`）は、パフォーマンスを最適化しペイロードサイズを削減するために、配列ベースの専用レスポンス形式を使用します。このガイドでは、これらのレスポンスの解釈方法を説明します。

<Note>
  `/v1/org/*` や `/v1/prompts/*` などのその他のエンドポイントは、標準的な JSON オブジェクト
  構造を使用しており、OpenAPI リファレンスに記載されています。
</Note>

## レポートのレスポンス構造

すべてのレポートエンドポイントは、次の最適化された形式でデータを返します：

```json theme={null}
{
  "data": [
    {
      "dimensions": ["example.com", "/some/path", "2023-10-01"],
      "metrics": [10, 0.05]
    },
    {
      "dimensions": ["another-site.com", "/different/path", "2023-10-02"],
      "metrics": [15, 0.08]
    }
  ],
  "info": {
    "query": {
      "date_interval": "day",
      "dimensions": ["hostname", "path", "date"],
      "filters": [
        {
          "field": "hostname",
          "operator": "in",
          "value": ["example.com", "another-site.com"]
        }
      ],
      "metrics": ["count", "share_of_voice"]
    },
    "total_rows": 200
  }
}
```

## レポートデータの解釈

### 配列の位置のマッピング

レポートのレスポンスを理解する鍵は、配列の位置がリクエストパラメーターと正確に対応していることです：

#### Dimensions 配列

値は、リクエスト内の dimensions の順序に対応します：

* `dimensions[0]` → リクエストした 1 番目の dimension（`hostname`）
* `dimensions[1]` → リクエストした 2 番目の dimension（`path`）
* `dimensions[2]` → リクエストした 3 番目の dimension（`date`）

#### Metrics 配列

値は、リクエスト内の metrics の順序に対応します：

* `metrics[0]` → リクエストした 1 番目の metric（`count`）
* `metrics[1]` → リクエストした 2 番目の metric（`share_of_voice`）

#### マッピングの例

上記の最初の結果オブジェクトの場合：

* **Hostname**: `dimensions[0]` = "example.com"
* **Path**: `dimensions[1]` = "/some/path"
* **Date**: `dimensions[2]` = "2023-10-01"
* **Count**: `metrics[0]` = 10
* **Share of Voice**: `metrics[1]` = 0.05

### Info オブジェクト

`info` オブジェクトは、クエリに関するメタデータを提供します：

| フィールド | 説明 |
| - | - |
| `query` | 送信したリクエストパラメーターがそのまま返されます |
| `total_rows` | 利用可能な結果の総数（ページネーションに便利です） |

## レポートのレスポンスを扱う

### データの処理

配列形式を従来のオブジェクト構造に変換する例：

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Process report response
  const processReportData = (response) => {
    const { dimensions: dimNames, metrics: metricNames } = response.info.query;
    
    return response.data.map(row => {
      const result = {};
      
      // Map dimensions
      dimNames.forEach((name, index) => {
        result[name] = row.dimensions[index];
      });
      
      // Map metrics
      metricNames.forEach((name, index) => {
        result[name] = row.metrics[index];
      });
      
      return result;
    });
  };

  // Usage
  const processedData = processReportData(apiResponse);
  // Result: [{ hostname: "example.com", path: "/some/path", date: "2023-10-01", count: 10, share_of_voice: 0.05 }]

  ```

  ```python Python theme={null}
  def process_report_data(response):
      """Convert array-based response to dict format"""
      query_info = response['info']['query']
      dim_names = query_info['dimensions']
      metric_names = query_info['metrics']

      results = []
      for row in response['data']:
          result = {}

          # Map dimensions
          for i, name in enumerate(dim_names):
              result[name] = row['dimensions'][i]

          # Map metrics
          for i, name in enumerate(metric_names):
              result[name] = row['metrics'][i]

          results.append(result)

      return results

  # Usage
  processed_data = process_report_data(api_response)
  # Result: [{"hostname": "example.com", "path": "/some/path", "date": "2023-10-01", "count": 10, "share_of_voice": 0.05}]
  ```

  ```php PHP theme={null}
  function processReportData($response) {
      $queryInfo = $response['info']['query'];
      $dimNames = $queryInfo['dimensions'];
      $metricNames = $queryInfo['metrics'];

      $results = [];
      foreach ($response['data'] as $row) {
          $result = [];

          // Map dimensions
          foreach ($dimNames as $index => $name) {
              $result[$name] = $row['dimensions'][$index];
          }

          // Map metrics
          foreach ($metricNames as $index => $name) {
              $result[$name] = $row['metrics'][$index];
          }

          $results[] = $result;
      }

      return $results;
  }
  ```
</CodeGroup>

## ベストプラクティス

1. **常に `info.query` オブジェクトを使用して**、レスポンスデータの構造を把握してください
2. 配列の位置をハードコードするのではなく、上記のマッピング例を使って**プログラムでレスポンスを処理してください**
3. `total_rows` フィールドを使って追加データがあるかどうかを判断し、**ページネーションを処理してください**
4. API の制限に達しないよう、**レート制限ヘッダーを監視してください**
5. リクエストパラメーターがユースケースで想定される dimensions と metrics に一致しているか、**検証してください**

## お困りの場合

予期しないレスポンス形式が返された場合や、特定のレポートレスポンスについて詳しく知りたい場合は、サポートチームまでお問い合わせください。