# コンバージョンデータの取得

> ユーザーアクションを分析し、マーケティング施策の効果を時系列で測定するためのコンバージョンデータを取得します。
>
> レート制限：1 秒あたり 2 リクエスト。

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/conversion/
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/conversion/:
    post:
      summary: コンバージョンデータの取得
      description: |-
        ユーザーアクションを分析し、マーケティング施策の効果を時系列で測定するためのコンバージョンデータを取得します。

        レート制限：1 秒あたり 2 リクエスト。
      operationId: retrieveConversionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConversionDataRequest"
            examples:
              basic:
                summary: 基本的なコンバージョンデータリクエスト
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                  from_period: 1
                  to_period: 6+
                  period_unit: month
                  date_type: purchase_date
                  segmentation: country
                  format: json
      responses:
        "200":
          description: コンバージョンデータを正常に取得しました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversionDataResponse"
              example:
                data: []
                value: 0
                value_from: 0
                value_to: 0
                compare_value_from: null
                compare_value_to: null
                title: Conversion rate from Paid to more than 6 months
                type: multi
                default_aggregation: sum
                description: If Х - the number of the 1st payments taken during the selected date, and Y - the amount of the renewals that happened after the 6 months since the selected date from those 1st payments, then Conversion = (Y / X) * 100%. For example, we had 100 1st subscriptions of various products on the 1st of January and among them 20 renewed on the 1st week of July (the 25th payment). On the 8th of July, we open the chart and see the conversion of the 1st of January = (20 / 100) * 100% = 20%. Then 30 more subscribers of the 1st of January renewed by the start of August (the 8th payment). We open the chart on the 1st of August and see that the conversion of the 1st of January = ((20+30) / 100) * 100% = 50%. This number shows which part of those who had their 1st payment on the 1st of January converted to the period > 6 months with any number of payments by the current moment.
                metric_name: from_paid_to_6_months_conversion
                is_json: true
                unit: percent
                recommended_period:
                  date_from: "2018-04-29"
                  date_to: "2024-12-31"
                  period_unit: month
            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:
    ConversionDataRequest:
      type: object
      required:
        - filters
        - from_period
        - to_period
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        from_period:
          oneOf:
            - type: string
            - type: "null"
          description: コンバージョン開始時のユーザーのサブスクリプション状態
        to_period:
          type: string
          description: コンバージョン後のユーザーの新しいサブスクリプション状態
        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
    ConversionDataResponse:
      type: object
      description: サブスクリプション状態間のユーザー推移を示すコンバージョンデータを含むレスポンス
      properties:
        data:
          type: array
          description: コンバージョンデータポイントの配列（集計指標の場合は空になることがあります）
          items:
            type: object
        value:
          type: number
          description: コンバージョン率の値
        value_from:
          type: integer
          description: コンバージョン開始時のサブスクリプション状態
        value_to:
          type: integer
          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: コンバージョン指標のタイプ
        default_aggregation:
          type: string
          description: この指標のデフォルト集計方法
        description:
          type: string
          description: コンバージョン率の計算方法の詳細な説明
        metric_name:
          type: string
          description: コンバージョン指標の内部名
        is_json:
          type: boolean
          description: データが JSON 形式かどうか
        unit:
          type: string
          description: 測定単位（コンバージョン率の場合は通常 'percent'）
        recommended_period:
          type: object
          description: このコンバージョン指標の推奨日付範囲
          properties:
            date_from:
              type: string
              description: 推奨期間の開始日
            date_to:
              type: string
              description: 推奨期間の終了日
            period_unit:
              type: string
              description: 推奨する期間の単位
    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: データを取得する特定のオファーを指定します
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        API リクエストは、シークレット API キーを Authorization ヘッダーとして使用して認証する必要があります。
        API キーはアプリ設定で確認できます。形式は `Api-Key {YOUR_SECRET_API_KEY}` です。
        例：`Api-Key secret_live_...`
```