一般信息

身份验证

所有 API 请求都需要一个 API 密钥。要获取密钥，请登录您的账户，进入 "开发工具">"API 密钥"。 您可以在请求中的api_key参数中插入密钥，或在授权 HTTP 标头下提供令牌。

速率限制

Singular API 的默认限制是

• 异步报告：最多同时运行 100 个异步报告。
• 同步报告：最多同时运行 3 个同步报告。
• 单个报告行数限制：每次查询最多 20 万行。
• 每日全局行数限制：单日最多 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"
      }
  }

可用维度和度量

有关每个字段的说明，请参阅 "度量标准和维度术语表"。

网络数据

跟踪器数据

组合数据

数据可用性端点

使用情况

该端点返回在给定日期内，每个数据源或数据连接器的数据是否可用。

我们建议在运行每日报告前使用该端点检查昨天的数据是否可用。

查询示例（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)

查询参数

输出示例（当展开为 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 与故障排除指南）。

要了解更多信息，请参阅《奇异报告 API 指南》中的 "查询过程"部分。

重要：

• 报告有时需要几分钟才能完成。
• 每份报告每 10 秒查询报告状态端点的次数不要超过一次。
• 设置超时。 在极少数情况下，报告可能会停留在 "已排队 "或 "已开始 "状态。如果30 分钟后状态不是 "完成 "或 "失败"，我们建议再次提交报告（这将为您提供一个新的报告 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（代替或补充任何默认维度）。

要了解自定义维度以及如何创建它们，请参阅自定义维度常见问题。

查询示例

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"}
      ]
    }
  }

队列度量终点

使用方法

使用此端点可检索您账户的所有队列指标和队列周期。这包括您配置 Singular 跟踪的任何应用程序内事件（请参阅 "事件常见问题"）。 然后，您可以在 "创建异步报告"（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"]
      }
  }

输出参数

转换指标端点

使用方法

使用此端点可检索账户的所有可用转换事件。然后，在创建异步报告端点中运行查询时，可以将这些事件指定为度量。

请注意，在创建异步报告查询中，您需要使用度量的 "名称"，而不是 "显示名称"。

查询示例

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 代码表示其他问题。

另请参阅：报告 API 常见问题和故障排除