# アナリティクスデータの取得

> チャートでのユーザー行動とパフォーマンス指標のインサイトを得るためのアナリティクスデータを取得します。
>
> このエンドポイントの収益は**イベントベース**です。各値は**トランザクション日**（購入、更新、または返金が発生した日）に紐付けられます。収益をトランザクション日ではなく各ユーザーのインストール日に紐付ける場合（例：Ads Manager との照合）は、コホートエンドポイント（`POST /api/v1/client-api/metrics/cohort/`）を使用してください。
>
> レート制限：1 秒あたり 2 リクエスト。

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/analytics/
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/analytics/:
    post:
      summary: アナリティクスデータの取得
      description: |-
        チャートでのユーザー行動とパフォーマンス指標のインサイトを得るためのアナリティクスデータを取得します。

        このエンドポイントの収益は**イベントベース**です。各値は**トランザクション日**（購入、更新、または返金が発生した日）に紐付けられます。収益をトランザクション日ではなく各ユーザーのインストール日に紐付ける場合（例：Ads Manager との照合）は、コホートエンドポイント（`POST /api/v1/client-api/metrics/cohort/`）を使用してください。

        レート制限：1 秒あたり 2 リクエスト。
      operationId: retrieveAnalyticsData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalyticsDataRequest"
            examples:
              basic:
                summary: 基本的なアナリティクスデータリクエスト
                value:
                  chart_id: revenue
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                    country:
                      - us
                    attribution_channel:
                      - social_media_influencers
                  period_unit: week
                  segmentation: attribution_campaign
      responses:
        "200":
          description: アナリティクスデータを正常に取得しました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsDataResponse"
              example:
                data:
                  revenue:
                    data: []
                    value: 0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: revenue
                    type: multi
                    default_aggregation: sum
                    description: |-
                      <div>Total money received from both subscriptions and one-time purchases. Does not include
                      revenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />
                      For example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />
                      revenue = 5*$10 + 1*$100 + 10*$50 = $650</div>
                    metric_name: Revenue
                    is_json: true
                    unit: USD
                    recommended_period: null
                  proceeds:
                    data: []
                    value: 0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: revenue
                    type: multi
                    default_aggregation: sum
                    description: |-
                      <div>Total money received from both subscriptions and one-time purchases. Does not include
                      revenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />
                      For example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />
                      revenue = 5*$10 + 1*$100 + 10*$50 = $650</div>
                    metric_name: Revenue
                    is_json: true
                    unit: USD
                    recommended_period: null
                  net_revenue:
                    data: []
                    value: 0
                    value_from: null
                    value_to: null
                    compare_value_from: null
                    compare_value_to: null
                    title: revenue
                    type: multi
                    default_aggregation: sum
                    description: |-
                      <div>Total money received from both subscriptions and one-time purchases. Does not include
                      revenue from subscriptions and purchases that were refunded afterward. Calculated before the store's fee.<br />
                      For example, there were 5 monthly $10 subs, 1 yearly $100 sub and 10 one-time $50 purchases today,<br />
                      revenue = 5*$10 + 1*$100 + 10*$50 = $650</div>
                    metric_name: Revenue
                    is_json: true
                    unit: USD
                    recommended_period: null
            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:
    AnalyticsDataRequest:
      type: object
      required:
        - chart_id
        - filters
      properties:
        chart_id:
          type: string
          enum:
            - revenue
            - mrr
            - arr
            - arppu
            - subscriptions_active
            - subscriptions_new
            - subscriptions_renewal_cancelled
            - subscriptions_expired
            - trials_active
            - trials_new
            - trials_renewal_cancelled
            - trials_expired
            - grace_period
            - billing_issue
            - refund_events
            - refund_money
            - non_subscriptions
            - arpu
            - installs
          description: 取得するチャートを指定します。1 回のリクエストで指定できるチャートタイプは 1 つのみです。
          example: revenue
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: アナリティクスデータを集計する時間間隔を指定します
          default: month
        date_type:
          type: string
          enum:
            - purchase_date
            - profile_install_date
          description: ユーザーの参加日として扱う日付を指定します
          default: purchase_date
        segmentation:
          type: string
          description: セグメンテーションの基準を設定します
        format:
          type: string
          enum:
            - json
            - csv
          description: エクスポートファイルの形式を指定します
          default: json
    AnalyticsDataResponse:
      type: object
      description: リクエストされたチャートタイプのアナリティクスデータを含むレスポンス
      properties:
        data:
          type: object
          description: 異なる指標タイプ（revenue、proceeds、net_revenue など）を含むオブジェクト
          additionalProperties:
            $ref: "#/components/schemas/MetricData"
    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: データを取得する特定のオファーを指定します
    MetricData:
      type: object
      description: 値、説明、メタデータを含む個別の指標データ
      properties:
        data:
          type: array
          description: 指標のデータポイントの配列（集計指標の場合は空になることがあります）
          items:
            type: object
        value:
          type: number
          description: この指標のメイン値
        value_from:
          type: number
          nullable: true
          description: 期間の開始値（該当する場合）
        value_to:
          type: number
          nullable: true
          description: 期間の終了値（該当する場合）
        compare_value_from:
          type: number
          nullable: true
          description: 比較期間の開始値（該当する場合）
        compare_value_to:
          type: number
          nullable: true
          description: 比較期間の終了値（該当する場合）
        title:
          type: string
          description: 指標の表示タイトル
        type:
          type: string
          description: 指標のタイプ（例：'multi'、'single'）
        default_aggregation:
          type: string
          description: デフォルトの集計方法（例：'sum'、'average'）
        description:
          type: string
          description: この指標が何を表し、どのように計算されるかを説明する HTML の説明文
        metric_name:
          type: string
          description: 指標の内部名
        is_json:
          type: boolean
          description: データが JSON 形式かどうか
        unit:
          type: string
          description: 測定単位（例：'USD'、'percent'）
        recommended_period:
          type: object
          nullable: true
          description: この指標の推奨日付範囲
          properties:
            date_from:
              type: string
              description: 推奨期間の開始日
            date_to:
              type: string
              description: 推奨期間の終了日
            period_unit:
              type: string
              description: 推奨する期間の単位（day、week、month など）
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        API リクエストは、シークレット API キーを Authorization ヘッダーとして使用して認証する必要があります。
        API キーはアプリ設定で確認できます。形式は `Api-Key {YOUR_SECRET_API_KEY}` です。
        例：`Api-Key secret_live_...`
```