# ファネルデータの取得

> コンバージョンプロセスの特定ステージにおけるユーザーの進行状況を追跡するためのファネルデータを取得します。
>
> レート制限：1 秒あたり 2 リクエスト。

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/funnel/
openapi: 3.1.0
info:
  title: Adapty エクスポートアナリティクス API
  version: 1.0.0
  description: |
    Adapty エクスポートアナリティクス API を使用すると、アナリティクスデータを CSV または JSON 形式でエクスポートできます。
    アプリのパフォーマンス指標をより深く分析し、レポートをカスタマイズして、
    時系列のトレンドを分析する柔軟性が得られます。この API を使用することで、詳細なアナリティクスデータを簡単に取得し、
    データインサイトを追跡・共有・改善することができます。
servers:
  - url: https://api-admin.adapty.io
    description: 本番サーバー
security:
  - apikeyAuth: []
paths:
  /api/v1/client-api/metrics/funnel/:
    post:
      summary: ファネルデータの取得
      description: |-
        コンバージョンプロセスの特定ステージにおけるユーザーの進行状況を追跡するためのファネルデータを取得します。

        レート制限：1 秒あたり 2 リクエスト。
      operationId: retrieveFunnelData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FunnelDataRequest"
            examples:
              basic:
                summary: 基本的なファネルデータリクエスト
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                    compare_date:
                      - "2023-01-01"
                      - "2023-12-31"
                    offer_category:
                      - promotional
                  period_unit: quarter
                  show_value_as: absolute
                  format: csv
      responses:
        "200":
          description: ファネルデータを正常に取得しました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FunnelDataResponse"
              example:
                data:
                  - title: Total
                    type: total
                    values:
                      - period: -2
                        title: Install
                        value: 2
                        value_relative: 100
                        relative_changes: 0
                        following_changes:
                          title: Drop off
                          value: 2
                          value_relative: 100
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
                      - period: -1
                        title: Paywall displayed
                        value: 0
                        value_relative: 0
                        relative_changes: 0
                        following_changes:
                          title: Drop off
                          value: 0
                          value_relative: 0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
            text/csv:
              schema:
                type: string
                description: CSV 形式のファネルデータ
        "400":
          description: リクエストが不正です
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: 認証されていません
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "429":
          description: レート制限を超過しました。API キーごとに 1 秒あたり最大 2 リクエストです。
components:
  schemas:
    FunnelDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: アナリティクスデータを集計する時間間隔を指定します
        show_value_as:
          type: string
          enum:
            - absolute
            - relative
            - both
          description: 値の表示方法を指定します
        segmentation:
          type: string
          description: セグメンテーションの基準を設定します
        format:
          type: string
          enum:
            - json
            - csv
          description: エクスポートファイルの形式を指定します
          default: json
    FunnelDataResponse:
      type: object
      description: コンバージョンステージを通じたユーザーの推移を示すファネル分析データを含むレスポンス
      properties:
        data:
          type: array
          description: コンバージョンプロセスの各ステージを示すファネルセグメントの配列
          items:
            $ref: "#/components/schemas/FunnelSegment"
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    MetricsFilters:
      type: object
      required:
        - date
      properties:
        date:
          type: array
          items:
            type: string
          description: チャートデータを取得する日付または期間を入力します
        compare_date:
          type: array
          items:
            type: string
          description: 比較する日付または期間を入力します
        store:
          type: array
          items:
            type: string
          description: 購入が行われたアプリストアでフィルタリングします
        country:
          type: array
          items:
            type: string
          description: 購入が行われた国の 2 文字の国コードでフィルタリングします
        store_product_id:
          type: array
          items:
            type: string
          description: アプリストアのプロダクト固有識別子
        duration:
          type: array
          items:
            type: string
          description: サブスクリプションの期間を指定します
        attribution_source:
          type: array
          items:
            type: string
          description: アトリビューションのソースインテグレーション
        attribution_status:
          type: array
          items:
            type: string
          description: アトリビューションがオーガニックか非オーガニックかを示します
        attribution_channel:
          type: array
          items:
            type: string
          description: トランザクションに至ったマーケティングチャネル
        attribution_campaign:
          type: array
          items:
            type: string
          description: トランザクションをもたらしたマーケティングキャンペーン
        attribution_adgroup:
          type: array
          items:
            type: string
          description: トランザクションをもたらしたアトリビューション広告グループ
        attribution_adset:
          type: array
          items:
            type: string
          description: トランザクションに至ったアトリビューション広告セット
        attribution_creative:
          type: array
          items:
            type: string
          description: 効果測定のために追跡される広告またはキャンペーン内の特定のビジュアルまたはテキスト要素
        offer_category:
          type: array
          items:
            type: string
          description: データを取得するオファーカテゴリを指定します
        offer_type:
          type: array
          items:
            type: string
          description: データを取得するオファータイプを指定します
        offer_id:
          type: array
          items:
            type: string
          description: データを取得する特定のオファーを指定します
    FunnelSegment:
      type: object
      description: コンバージョンプロセスのステージを表すファネルセグメント
      properties:
        title:
          type: string
          description: このファネルセグメントの表示タイトル
        type:
          type: string
          description: ファネルセグメントのタイプ（集計データの場合は 'total'）
        values:
          type: array
          description: ステージを通じた推移を示すファネル値の配列
          items:
            $ref: "#/components/schemas/FunnelValue"
    FunnelValue:
      type: object
      description: ユーザーの推移と離脱を示す個別のファネルステージ値
      properties:
        period:
          type: integer
          description: ファネル内の期間番号（-2 = インストール、-1 = ペイウォール表示など）
        title:
          type: string
          description: このファネルステージの表示タイトル
        value:
          type: integer
          description: このステージに到達したユーザー数
        value_relative:
          type: number
          description: 最初のステージを基準としたこのステージへの到達ユーザーの割合
        relative_changes:
          type: number
          description: 前の期間と比較したコンバージョン率の変化
        following_changes:
          type: object
          description: このステージ後に離脱したユーザーに関する情報
          properties:
            title:
              type: string
              description: 離脱ステージのタイトル
            value:
              type: integer
              description: 離脱したユーザー数
            value_relative:
              type: number
              description: 離脱したユーザーの割合
        churn_reason_title:
          type: string
          description: このステージでのチャーン理由を説明するタイトル
        churn_reasons:
          type: array
          description: 具体的なチャーン理由の配列
          items:
            type: object
        values:
          type: array
          description: このファネルステージの追加ネスト値
          items:
            type: object
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        API リクエストは、シークレット API キーを Authorization ヘッダーとして使用して認証する必要があります。
        API キーはアプリ設定で確認できます。形式は `Api-Key {YOUR_SECRET_API_KEY}` です。
        例：`Api-Key secret_live_...`
```