一般情報

認証

すべてのAPIリクエストにはAPIキーが必要です。キーを取得するには、アカウントにログインし、デベロッパーツール > APIキーに 進みます。リクエストのapi_keyパラメータにキーを挿入するか、Authorization HTTPヘッダの下にトークンを提供することができます。

レート制限

Singular APIのデフォルトの制限は以下の通りです：

• 非同期レポート: 最大100件の非同期レポートを同時に実行できます。
• 同期レポート: 最大3つの同期レポートを同時に実行できます。
• 単一レポート行数制限：クエリごとに最大200K行。
• 1日のグローバル行数制限： 1日に最大3M行（すべてのクエリで共有）。

Singularは、すべてのお客様に高品質なサービスを継続的に提供するために、所定のエンドポイントのレート制限を調整する権利を留保します。デフォルトの制限を超える特定のニーズがある場合はお問い合わせください。

レポートAPIエンドポイントのリスト

以下のAPIエンドポイントが利用可能です：

非同期レポート作成エンドポイント

import requests
  url = "https://api.singular.net/api/v2.0/create_async_report"
  query_params = {"api_key": "<API KEY>"}
  payload = {
    "dimensions":"app,source,os,country_field",
    "metrics": "custom_impressions,custom_clicks,custom_installs",
    "start_date":"2020-01-01",
    "end_date": "2020-01-01",
    "time_breakdown": "all",
    "format": "csv",
    "country_code_format": "iso"
  }
  response = requests.post(url=url, params=query_params, data=payload)
  print(response.text)

{
      "status": 0,
      "substatus": 0,
      "value": {
          "report_id": "5cfdb747dd464cd09a9c463e5be9691f"
      }
  }

使用可能なディメンションとメトリックス

各フィールドの説明については、『Metrics and Dimensions Glossary』を参照してください。

ネットワーク・データ

トラッカーデータ

結合データ

データの可用性エンドポイント

使用法

このエンドポイントは、指定された日に、ソースまたはデータ コネクターのそれぞれについてデータが利用可能かどうかを返します。

このエンドポイントを使用して、日次レポートを実行する前に、昨日のデータがすでに利用可能かどうかを確認することをお勧めします。

サンプル・クエリ（Python）

import requests

  url = "https://api.singular.net/api/v2.0/data_availability_status"
  queryparams = {
    "api_key":"<API_KEY>",
    "expanded":"true",
    "format": "json",
    "data_date":"2021-02-01",
    "display_non_active_sources":"true"
  }
  
  response = requests.get(url=url, params=queryparams)

クエリ・パラメータ

サンプル出力（expanded=trueの場合）

{
      "status": 0, 
      "substatus": 0, 
      "value": {
          "is_all_data_available": false,
          "data_connectors": [{
              "data_connector_id": "dgd7934875", 
              "data_connector_source_name": "Vungle", 
              "data_connector_username": "ua@mycompany.com", 
              "is_active_last_30_days": true, 
              "is_available": true, 
              "is_empty_data": false, 
              "last_updated_utc": "2021-02-08T10:10:07", 
              "data_connector_timestamp_utc": "2021-02-08T10:10:07", 
              "status": "data populated"
          }, {
              "data_connector_id": "youi293478", 
              "data_connector_source_name": "IronSource", 
              "data_connector_username": "ua@mycompany.com", 
              "is_active_last_30_days": true, 
              "is_available": false, 
              "is_empty_data": "N/A", 
              "last_updated_utc": "N/A", 
              "data_connector_timestamp_utc": "N/A", 
              "status": "data not populated"
          }]
      }
  }

出力パラメータ

{'is_all_data available': false,
  'data_sources': [
  {'username': u'facebook@singular.net',
   'status': 'data populated',
   'is_empty_data': false,
   'is_active_last_30_days': true,
   'last_updated_utc': '2018-05-03T10:12:18'
   'source': u'Facebook',
   'is_available': true},
   {'username': u'vungle@singular.net',
   'status': 'data populated',
   'is_empty_data': true,
   'is_active_last_30_days': true,
   'last_updated_utc': '2018-05-03T10:12:18'
   'source': u'Vungle',
   'is_available': true},
   {'username': u'applovin@singular.net',
   'status': 'data not populated',
   'is_empty_data': N/A,
   'is_active_last_30_days': true,
   'last_updated_utc': N/A
   'source': u'Applovin',
   'is_available': false}
  ]}

レポートステータスの取得 エンドポイント

使用法

このエンドポイントは、非同期レポートの作成エンドポイントを使用して生成された所定のレポートのステータスを返します。レポートの実行が終了した場合、エンドポイントはダウンロード URL も返します。

レポートが失敗した場合、エンドポイントは問題のトラブルシューティングに使用できるエラーメッセージを返します（エラーコードの表、およびAPI FAQ とトラブルシューティングのガイドを参照してください）。

詳しくはSingular Reporting APIガイドの クエリプロセスセクションを参照してください。

重要です：

• レポートが完了するまでに数分かかることがあります。
• レポートごとに10秒に1回以上レポートステータスのエンドポイントに問い合わせないでください。
• タイムアウトを設定します。 稀なケースですが、レポートが "Queued "または "Started "ステータスに留まることがあります。30分経ってもステータスが「Done（完了）」または「Failed（失敗）」でない場合は、レポートを再度送信することをお勧めします（これにより、クエリ用の新しいレポートIDが得られます）。

サンプルクエリ

import requests
  url = "https://api.singular.net/api/v2.0/get_report_status"
  querystring = {
    "report_id":"5cfdb747dd45be9691f",
    "api_key": "<API KEY>"
  }
  response = requests.get(url=url, params=querystring)
  print(response.text)

クエリ・パラメータ

サンプル出力

{
    "status": 0,
    "substatus": 0,
    "value": {
        "status": "DONE",
        "url_expires_in": 3600,
        "generated_url_time_in_utc": "2018-05-13T08:26:18.457690+00:00",
        "url_expired_time_in_utc": "2018-05-13T09:26:18.457690+00:00",
        "download_url": "https://singular-reports-results.s3.amazonaws.com/singular/xxxxxxxxx",
        "report_id": "5cfdb747dd45be9691f"
    }
  }

出力パラメータ

フィルター・エンドポイント

使用法

このヘルパー・エンドポイントを使用して、レポートをフィルタリングできるディメンジョンの最新リストと、各ディメンジョンで可能な値を取得します。

サンプル・クエリ

import requests
  url = "https://api.singular.net/api/v2.0/reporting/filters"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

クエリ・パラメータ

サンプル出力

{
    "status": 0,
    "substatus": 0,
    "value": {
      "dimensions": [
        {
          "name": "os",
          "display_name": "OS",
          "values": [
              {"name": 4, "display_name": "Android"},
              {"name": 1, "display_name": "iOS"}
            ],
        },
        {
          "name": "source",
          "display_name": "Source",
          "values": [{"name": "adwords", "display_name": "AdWords"}]
        }
      ]
    }
  }

カスタム・ディメンション・エンドポイント

使用法

このエンドポイントを使用して、アカウント用に構成されたカスタム・ディメンションの ID を取得します。その後、[非同期レポートの作成] エンドポイントをクエリするときに、カスタム・ディメンジョン ID を使用できます (既定のディメンジョンの代わりに、または既定のディメンジョンに加えて)。

カスタム・ディメンションとその作成方法については、カスタム・ディメンション FAQ を参照してください。

サンプル・クエリ

import requests
  url = "https://api.singular.net/api/custom_dimensions"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

クエリ・パラメータ

サンプル出力

{
    "status": 0,
    "substatus": 0,
    "value": {
      "custom_dimensions": [
        {"display_name": "Channel Type", "id": "e471cb6b83684532e5e83cd"},
        {"display_name": "Region", "id": "1dcfdb1ad861fba4b098e2"}
      ]
    }
  }

コホート指標エンドポイント

使用法

このエンドポイントを使用して、アカウントで利用可能なすべてのコホート・メトリクスとコホート期間を取得します。非同期レポート作成エンドポイントでクエリーを実行する際に、これらのメトリクスと期間を指定できます。

Create Async Reportクエリでは、メトリックの「表示名」ではなく「名前」を使用する必要があることに注意してください。

サンプル クエリ

import requests
  url = "https://api.singular.net/api/cohort_metrics"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

クエリーパラメーター

サンプル出力

{
      "status": 0,
      "substatus": 0,
      "value": {
          "metrics": [
              {"display_name": "ROI","name": "roi"},
              {"display_name": "Revenue","name": "revenue"}
          ],
          "periods": ["1d","3d","5d","7d","14d","30d","actual"]
      }
  }

出力パラメータ

変換指標エンドポイント

使用方法

このエンドポイントを使用して、アカウントで利用可能なすべてのコンバージョン イベントを取得します。その後、Create Async Report エンドポイントでクエリーを実行するときに、これらのイベントをメトリックとして指定できます。

Create Async Reportクエリでは、メトリックの「表示名」ではなく「名前」を使用する必要があることに注意してください。

サンプル クエリ

import requests
  url = "https://api.singular.net/api/conversion_metrics"
  params = {'api_key': "<API KEY>"}
  result = requests.get(url=url, params=params)
  print result.json()

クエリーパラメーター

サンプル出力

{
    "status": 0, 
    "substatus": 0, 
    "value": {
      "metrics": [
        {"display_name": "5-second video view", "name": "87dfg34453hsfg6f"}, 
        {"display_name": "5-second video view CPE", "name": "87dfg34453hsfg6fCPE"},   
        {"display_name": "Sign up", "name": "iuq353fidr76w846fha"}, 
        {"display_name": "Sign up CPE", "name": "iuq353fidr76w846fhaCPE"}, 
        {"display_name": "Post engagement", "name": "b59cje9fcgw0th"}, 
        {"display_name": "Post engagement CPE", "name": "b59cje9fcgw0thCPE"},
      ]
    }
  }

出力パラメータ

エラーコード

Singularは標準的なHTTPレスポンスコードを使用して、APIリクエストの成功または失敗を示します。一般的に、200 のコードは成功に対応し、4xx の範囲のコードは提供された情報が失敗したエラー (必須パラメータが省略されたなど) を示し、5xx のコードはその他の問題を示します。

参照：Reporting API FAQおよびトラブルシューティング