# コホートデータの取得

> ユーザーグループを時系列で追跡するためのコホートデータを取得します。
>
> このエンドポイントの収益は**インストール日コホート**ベースです。各ユーザーの収益はトランザクション日ではなく**インストール日**に紐付けられます。レスポンスには `total_revenue_usd` と `total_proceeds_usd` が含まれます。インストール日ベースでもある Ads Manager との内部レポート照合には、アナリティクスエンドポイントではなくこのエンドポイントを使用してください。
>
> レート制限：1 秒あたり 2 リクエスト。

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/cohort/
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/cohort/:
    post:
      summary: コホートデータの取得
      description: |-
        ユーザーグループを時系列で追跡するためのコホートデータを取得します。

        このエンドポイントの収益は**インストール日コホート**ベースです。各ユーザーの収益はトランザクション日ではなく**インストール日**に紐付けられます。レスポンスには `total_revenue_usd` と `total_proceeds_usd` が含まれます。インストール日ベースでもある Ads Manager との内部レポート照合には、アナリティクスエンドポイントではなくこのエンドポイントを使用してください。

        レート制限：1 秒あたり 2 リクエスト。
      operationId: retrieveCohortData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CohortDataRequest"
            examples:
              basic:
                summary: 基本的なコホートデータリクエスト
                value:
                  filters:
                    date:
                      - "2024-04-01"
                      - "2024-09-30"
                    store:
                      - app_store
                    country:
                      - us
                  period_unit: month
                  period_type: renewals
                  value_type: absolute
                  value_field: subscriptions
      responses:
        "200":
          description: コホートデータを正常に取得しました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CohortDataResponse"
              example:
                data:
                  - segment_start_date: "2024-04-01"
                    type: total
                    title: Total
                    total_installs: 0
                    total_subscriptions: 0
                    total_paid_subscribers: 0
                    total_revenue_usd: 0
                    total_proceeds_usd: 0
                    total_net_revenue_usd: 0
                    total_anrpas_usd: 0
                    total_appas_usd: 0
                    total_arpas_usd: 0
                    total_anrppu_usd: 0
                    total_apppu_usd: 0
                    total_arppu_usd: 0
                    total_anrpu_usd: 0
                    total_appu_usd: 0
                    total_arpu_usd: 0
                    predict: null
                    values:
                      - arpas_usd: 0
                        appas_usd: 0
                        anrpas_usd: 0
                        anrppu_usd: 0
                        apppu_usd: 0
                        arppu_usd: 0
                        anrpu_usd: 0
                        appu_usd: 0
                        arpu_usd: 0
                        installs: 0
                        period: 1
                        revenue_usd: 0
                        proceeds_usd: 0
                        net_revenue_usd: 0
                        revenue_relative: 0
                        proceeds_relative: 0
                        net_revenue_relative: 0
                        subscriptions: 0
                        subscriptions_relative: 0
                        subscribers: 0
                        subscribers_relative: 0
                        currently_active_period: false
            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:
    CohortDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: アナリティクスデータを集計する時間間隔を指定します
          default: month
        period_type:
          type: string
          enum:
            - renewals
            - days
          description: 更新回数または日数でデータを分析します
          default: renewals
        value_type:
          type: string
          enum:
            - absolute
            - relative
          description: 値の表示方法を指定します
          default: absolute
        value_field:
          type: string
          enum:
            - revenue
            - arppu
            - arpu
            - arpas
            - subscribers
            - subscriptions
          description: 表示する値のタイプを指定します
          default: revenue
        accounting_type:
          type: string
          enum:
            - revenue
            - proceeds
            - net_revenue
          description: 使用する会計方式
          default: revenue
        renewal_days:
          type: array
          items:
            type: integer
          description: period_type=days のコホートタイプに使用する、アプリインストールからの経過日数のリスト
        prediction_months:
          type: integer
          enum:
            - 3
            - 6
            - 9
            - 12
            - 18
            - 24
          description: 予測の月数を入力します
          default: 12
        format:
          type: string
          enum:
            - json
            - csv
          description: エクスポートファイルの形式を指定します
          default: json
    CohortDataResponse:
      type: object
      description: ユーザー行動を時系列で示すコホート分析データを含むレスポンス
      properties:
        data:
          type: array
          description: 同じ期間に開始したユーザーグループを表すコホートセグメントの配列
          items:
            $ref: "#/components/schemas/CohortSegment"
    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: データを取得する特定のオファーを指定します
    CohortSegment:
      type: object
      description: 同じ期間に開始したユーザーを表すコホートセグメント
      properties:
        segment_start_date:
          type: string
          description: このコホートセグメントの開始日
        type:
          type: string
          description: セグメントのタイプ（集計データの場合は 'total'、個別コホートの場合は 'single'）
        title:
          type: string
          description: このコホートセグメントの表示タイトル
        total_installs:
          type: integer
          description: このコホートの総アプリインストール数
        total_subscriptions:
          type: integer
          description: このコホートの総サブスクリプション数
        total_paid_subscribers:
          type: integer
          description: このコホートの総有料サブスクライバー数
        total_revenue_usd:
          type: number
          description: このコホートの総収益（USD）
        total_proceeds_usd:
          type: number
          description: このコホートの総プロシード（USD、ストア手数料控除後）
        total_net_revenue_usd:
          type: number
          description: このコホートの総純収益（USD）
        total_anrpas_usd:
          type: number
          description: アクティブサブスクライバー 1 人あたりの平均純収益（ANRPAS）（USD）の合計
        total_appas_usd:
          type: number
          description: アクティブサブスクライバー 1 人あたりの平均プロシード（APPAS）（USD）の合計
        total_arpas_usd:
          type: number
          description: アクティブサブスクライバー 1 人あたりの平均収益（ARPAS）（USD）の合計
        total_anrppu_usd:
          type: number
          description: 有料ユーザー 1 人あたりの平均純収益（ANRPPU）（USD）の合計
        total_apppu_usd:
          type: number
          description: 有料ユーザー 1 人あたりの平均プロシード（APPPU）（USD）の合計
        total_arppu_usd:
          type: number
          description: 有料ユーザー 1 人あたりの平均収益（ARPPU）（USD）の合計
        total_anrpu_usd:
          type: number
          description: ユーザー 1 人あたりの平均純収益（ANRPU）（USD）の合計
        total_appu_usd:
          type: number
          description: ユーザー 1 人あたりの平均プロシード（APPU）（USD）の合計
        total_arpu_usd:
          type: number
          description: ユーザー 1 人あたりの平均収益（ARPU）（USD）の合計
        predict:
          type: object
          nullable: true
          description: このコホートの予測データ（利用可能な場合）
        values:
          type: array
          description: コホートの時系列パフォーマンスを示す期間別値の配列
          items:
            $ref: "#/components/schemas/CohortValue"
    CohortValue:
      type: object
      description: 特定の期間のパフォーマンス指標を示す、コホートセグメント内の個別期間値
      properties:
        arpas_usd:
          type: number
          description: この期間のアクティブサブスクライバー 1 人あたりの平均収益（USD）
        appas_usd:
          type: number
          description: この期間のアクティブサブスクライバー 1 人あたりの平均プロシード（USD）
        anrpas_usd:
          type: number
          description: この期間のアクティブサブスクライバー 1 人あたりの平均純収益（USD）
        anrppu_usd:
          type: number
          description: この期間の有料ユーザー 1 人あたりの平均純収益（USD）
        apppu_usd:
          type: number
          description: この期間の有料ユーザー 1 人あたりの平均プロシード（USD）
        arppu_usd:
          type: number
          description: この期間の有料ユーザー 1 人あたりの平均収益（USD）
        anrpu_usd:
          type: number
          description: この期間のユーザー 1 人あたりの平均純収益（USD）
        appu_usd:
          type: number
          description: この期間のユーザー 1 人あたりの平均プロシード（USD）
        arpu_usd:
          type: number
          description: この期間のユーザー 1 人あたりの平均収益（USD）
        installs:
          type: integer
          description: この期間のアプリインストール数
        period:
          type: integer
          description: 期間番号（1 = 第 1 期間、2 = 第 2 期間など）
        revenue_usd:
          type: number
          description: この期間の総収益（USD）
        proceeds_usd:
          type: number
          description: この期間の総プロシード（USD、ストア手数料控除後）
        net_revenue_usd:
          type: number
          description: この期間の総純収益（USD）
        revenue_relative:
          type: number
          description: 第 1 期間を基準とした収益の割合（100% = 第 1 期間）
        proceeds_relative:
          type: number
          description: 第 1 期間を基準としたプロシードの割合（100% = 第 1 期間）
        net_revenue_relative:
          type: number
          description: 第 1 期間を基準とした純収益の割合（100% = 第 1 期間）
        subscriptions:
          type: integer
          description: この期間のサブスクリプション数
        subscriptions_relative:
          type: number
          description: 第 1 期間を基準としたサブスクリプションの割合（100% = 第 1 期間）
        subscribers:
          type: integer
          description: この期間のサブスクライバー数
        subscribers_relative:
          type: number
          description: 第 1 期間を基準としたサブスクライバーの割合（100% = 第 1 期間）
        currently_active_period:
          type: boolean
          description: このコホートの現在アクティブな期間かどうか
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        API リクエストは、シークレット API キーを Authorization ヘッダーとして使用して認証する必要があります。
        API キーはアプリ設定で確認できます。形式は `Api-Key {YOUR_SECRET_API_KEY}` です。
        例：`Api-Key secret_live_...`
```