05.review-chart

レビューチャート

概要説明

レビューチャートエンドポイントは、選択された製品の時系列レビュー数を返します。AI視点と特定視点（SPVP）の2つの処理モードをサポートします。両方のモードは時間経過に伴う累積数を返し、各シリーズアイテムに製品詳細を含みます。

アクティビティ図

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    Client[Client Application]
    API[ProductAnalyzerController]
    Dataset[Dataset Validation]
    AService[ProductAnalyzerService]
    SService[SpvpService]
    Database[(Database)]
    
    Client --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>GET リクエスト送信</p>
        </div>
    ]
    Step1 --> API

    API --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>データセット検証</p>
        </div>
    ]
    Step2 --> Dataset

    Dataset --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>パラメータ処理</p>
        </div>
    ]
    Step3 --> API

    API --- Step4A[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4A</span>
            <p style='margin-top: 8px'>AI視点</p>
        </div>
    ]
    Step4A --> AService
    AService --> Database
    Database --> AService

    API --- Step4B[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4B</span>
            <p style='margin-top: 8px'>特定視点</p>
        </div>
    ]
    Step4B --> SService
    SService --> Database
    Database --> SService

    AService --- Step5A[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5A</span>
            <p style='margin-top: 8px'>レスポンスフォーマット</p>
        </div>
    ]
    SService --- Step5B[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5B</span>
            <p style='margin-top: 8px'>レスポンスフォーマット</p>
        </div>
    ]
    Step5A --> API
    Step5B --> API

    API --- Step6[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6</span>
            <p style='margin-top: 8px'>JSON レスポンス送信</p>
        </div>
    ]
    Step6 --> Client
    
    %% Styling
    style Client fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style API fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style Dataset fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style AService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style SService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style Database fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4A fill:transparent,stroke:transparent,stroke-width:1px
    style Step4B fill:transparent,stroke:transparent,stroke-width:1px
    style Step5A fill:transparent,stroke:transparent,stroke-width:1px
    style Step5B fill:transparent,stroke:transparent,stroke-width:1px
    style Step6 fill:transparent,stroke:transparent,stroke-width:1px

Swagger リンク

API: Review Chart API

API エンドポイント

  • GET /api/v1/general/analysis/{wldh_slug}/review-chart

クエリパラメータ

パラメータ タイプ 必須 説明
product_ids array はい 分析対象の製品ID配列
viewpoint_type string はい 視点タイプ（ai または spvp）
viewpoint_id string 条件付き SPVPモードの場合の視点ID
start_date string いいえ 開始日（YYYY-MM-DD形式）
end_date string いいえ 終了日（YYYY-MM-DD形式）
group_by string いいえ グループ化単位（day, week, month）

レスポンス形式

AI視点モード

{
  "success": true,
  "data": {
    "series": [
      {
        "product_id": "prod123",
        "product_name": "製品名",
        "product_image": "https://example.com/image.jpg",
        "data": [
          {
            "date": "2024-01-01",
            "count": 10,
            "cumulative": 10
          },
          {
            "date": "2024-01-02",
            "count": 15,
            "cumulative": 25
          }
        ]
      }
    ],
    "metadata": {
      "total_products": 1,
      "date_range": {
        "start": "2024-01-01",
        "end": "2024-01-31"
      }
    }
  }
}

特定視点（SPVP）モード

{
  "success": true,
  "data": {
    "series": [
      {
        "product_id": "prod123",
        "product_name": "製品名",
        "product_image": "https://example.com/image.jpg",
        "viewpoint_id": "vp456",
        "viewpoint_name": "視点名",
        "data": [
          {
            "date": "2024-01-01",
            "count": 8,
            "cumulative": 8
          },
          {
            "date": "2024-01-02",
            "count": 12,
            "cumulative": 20
          }
        ]
      }
    ],
    "metadata": {
      "total_products": 1,
      "date_range": {
        "start": "2024-01-01",
        "end": "2024-01-31"
      }
    }
  }
}

エラーハンドリング

コード メッセージ 説明
400 Bad Request 無効なパラメータ
404 Dataset not found データセットが見つかりません
422 Validation failed バリデーションエラー
500 Internal server error サーバー内部エラー

使用例

AI視点でのレビューチャート取得

curl -X GET "https://api.example.com/api/v1/general/analysis/dataset-slug/review-chart?product_ids[]=prod123&product_ids[]=prod456&viewpoint_type=ai&start_date=2024-01-01&end_date=2024-01-31&group_by=day"

特定視点でのレビューチャート取得

curl -X GET "https://api.example.com/api/v1/general/analysis/dataset-slug/review-chart?product_ids[]=prod123&viewpoint_type=spvp&viewpoint_id=vp456&start_date=2024-01-01&end_date=2024-01-31&group_by=week"

データ処理の詳細

累積計算

  • 各日付のレビュー数は、その日までの累積数を表します
  • 時系列の一貫性を保つため、欠損データは0として扱われます

グループ化オプション

  • day: 日単位での集計
  • week: 週単位での集計（月曜日開始）
  • month: 月単位での集計

パフォーマンス最適化

  • 大量のデータセットに対しては、適切な日付範囲の指定を推奨します
  • 製品数が多い場合は、一度に分析する製品数を制限することをお勧めします