本指南适用于Singular合作伙伴。合作伙伴可以通过Partner Portal或API访问部分广告商数据。

如果您是Singular客户，请参阅以下链接：报告API参考以及 Singular报告API入门。

作为Singular合作伙伴，您可以使用Singular报告API访问已启用Singular的广告商数据。

通过API访问的每个组织的数据，与您在Partner Portal中可以访问的数据相同。

报告API基础

在运行报告之前，您需要以下信息：

您的Singular API密钥。 您可以在Partner Portal中找到它（请参阅使用Partner Portal）。
您希望访问的广告商的组织密钥。 查询获取客户账户API端点以获取广告商名称及每个广告商的唯一组织密钥。
报告筛选选项。 使用您的API密钥和广告商的组织密钥查询筛选器API端点。每个组织的选项可能不同。
事件和分组期间。 请检查Partner Portal。该广告商在Portal中提供的任何事件也可通过API使用。

运行报告时，请使用以下两个主要端点：

使用Create Async Report端点查询您需要的数据。
使用Get Report Status端点检查报告状态，并在完成运行后访问报告。

获取客户账户端点

GET

https://api.singular.net/api/v2.0/get_customer_accounts

使用说明

使用此端点检索广告商列表。列表包括您网络中正在运行广告活动的所有Singular客户，但排除了选择不与您共享数据的客户。

然后，您可以使用组织密钥查询Create Async Report端点。

查询参数

参数	格式	说明
api_key	字符串	您的Singular API密钥

示例输出

"organizations":[

    {

        "display_name":"Awesome Games",

        "organization_key": "aw_games"

    },

    ...

]

输出详情

参数	说明
display_name	广告商的完整名称
organization_key	Singular中广告商的唯一密钥（用于查询Create Async Report端点）。

筛选器端点

GET

https://api.singular.net/api/v2.0/reporting/filters

使用说明

使用此辅助端点获取最新的维度列表，您可以根据这些维度筛选报告，并了解每个维度的可能值。您必须指定相关广告商的组织密钥。

示例查询 (Python)

import requests

url = "https://api.singular.net/api/v2.0/reporting/filters"

params = {

    "api_key": API_KEY,

    "organization_key": ORGANIZATION_KEY

}

result = requests.get(url=url, params=params)

print result.json()

查询参数

参数	格式	说明
api_key	字符串	来自Partner Portal的API密钥
organization_key	字符串	获取客户账户端点返回的组织密钥

示例输出

{

  "status": 0,

  "substatus": 0,

  "value": { "dimensions": [

    {

      "name": "os",

      "display_name": "操作系统",

      "values": [
        {"name":4,"display_name":"安卓"},
        {"name":1,"display_name":"iOS"}
      ],

    },

    {

      "name": "source",

      "display_name": "来源",

      "values": [
        {"name": "adwords", "display_name": "AdWords"}
      ]

    }

  ]}

}

创建异步报告端点

POST

https://api.singular.net/api/v2.0/create_async_report

使用说明

此端点是从Singular获取报告数据的主要端点。端点根据组织密钥、报告维度、指标、日期及其他详细信息生成异步报告查询，并返回报告ID。

接下来，请查询获取报告状态端点，以检查报告是否完成并获取下载URL。

限制

单日的API请求对返回行数无限制。
单个请求最多可以查询30天的数据，最大返回记录数为100,000。如果查询超过100,000条记录，请使用额外的筛选条件。
建议在每天或每周获取数据时，将多日查询拆分为单日查询，并迭代整个时间段。

示例查询 (Python)

import requests

url = "https://api.singular.net/api/v2.0/create_async_report"

query_params = {"api_key": API_KEY}

payload = {

  "organization_key": ORGANIZATION_KEY,

  "dimensions":"app,source,os,country_field",

  "metrics": "custom_impressions,custom_clicks,custom_installs",

  "start_date":"2022-08-01",

  "end_date": "2022-08-02",

  "time_breakdown": "all",

  "format": "csv",

  "country_code_format": "iso"

}

response = requests.post(url=url, params=query_params, data=payload)

查询参数

参数	格式	说明	示例
基本参数
api_key	字符串	从Partner Portal提供的API密钥
organization_key	字符串	您想运行报告的广告商的组织密钥
start_date	日期	报告的开始日期
end_date	日期	报告的结束日期
time_breakdown	字符串	按“day”、“week”、“month”或“all”细分结果。“all”将显示整个时间段的聚合数据。
字段选择参数
dimensions	字符串	以逗号分隔的维度列表。可用维度请参见下文的“支持的维度”。更多详细信息请参阅指标和维度。
metrics	字符串	您想包含在报告中的指标列表（以逗号分隔）。支持的指标请参见下文的“支持的指标”。更多详细信息请参阅指标和维度。
cohort_metrics	字符串	按名称指定的分组指标列表（以逗号分隔）。更多详细信息请参阅什么是分组指标？。每个广告商可用的自定义事件和分组指标可在Partner Portal中查看。	'cohort_metrics': '815782610a1ddf,revenue'
cohort_periods	字符串	分组期间列表（以逗号分隔）。更多详细信息请参阅什么是分组指标？。每个广告商的可用分组期间可在Partner Portal中查看。	'cohort_periods': '7d,14d,ltv'
筛选参数
app	字符串	用于过滤查询结果的应用名称列表（以逗号分隔）。要检索应用名称列表，请使用筛选器端点。	'app': 'my_app1,my_app2'
source	字符串	用于过滤的广告网络（及其他来源）列表（以逗号分隔）。要检索广告网络名称列表，请使用筛选器端点。	'source': 'facebook,adwords'
filters	JSON	包含多个过滤条件的JSON对象列表，每个对象包含维度、操作符和值。用于应用高级过滤条件。多个过滤条件之间是“与”的关系。要检索可用维度及其值，请使用筛选器端点。	'filters': '[{"dimension": "os", "operator": "in","values": [1, 4]}, {"dimension": "source", "operator": "not in", "values": ["adwords"]}]'
格式化参数
format	字符串	查询结果的输出格式。选项：“json”（默认）或“csv”。	'format':'csv'
country_code_format	字符串	国家代码格式。“iso3”（默认）或“iso”。
display_alignment	布尔值	设置为“true”时，结果将包含对齐行，以解释广告活动和创意统计之间的差异。更多信息请参阅为什么创意指标包含负值？。

示例输出

{

    "status": 0,

    "substatus": 0,

    "value": {

        "report_id": "5cfdb747dd464cd09a9c463e5be9691f"

    }

}

获取报告状态端点

GET

https://api.singular.net/api/v2.0/get_report_status

使用说明

此端点返回通过Create Async Report端点生成的特定报告的状态。如果报告已完成运行，此端点还会返回下载URL。如果报告运行失败，则返回一个错误消息，您可以使用此消息进行故障排除。（详细信息请参阅错误代码表和 API FAQ和故障排除指南）。

注意：

报告可能需要几分钟时间才能完成。
不要对同一报告每10秒查询一次以上。
设置超时：在极少数情况下，报告可能会卡在“Queued”或“Started”状态。如果状态在30分钟后仍未更改为“Done”或“Failed”，建议重新提交报告（这将为您生成一个新的报告ID）。

示例查询 (Python)

import requests

url = "https://api.singular.net/api/v2.0/get_report_status"

querystring = {

    "report_id": REPORT_ID,

    "api_key": API_KEY

}

response = requests.get(url=url, params=querystring)

print(response.text)

查询参数

参数	格式	说明
api_key	字符串	从Singular控制台提供的API密钥
report_id	字符串	通过Create Async Report端点返回的报告ID

示例输出

{

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

    }

}

输出详情

参数	格式	说明
status	字符串	可能的值： "QUEUED"：报告正在排队。 "STARTED"：报告正在运行。 "DONE"：报告已准备好。下载URL请参阅download_URL参数。 "FAILED"：报告未成功完成。阅读附加错误消息并检查错误代码表和常见问题解答和故障排除页面。
generated_url_time_in_utc	时间戳	生成下载URL的时间
url_expires_in	整数	下载URL的过期时间（以秒为单位）。
url_expired_time_in_utc	时间戳	URL过期的时间。
download_url	URL	用于下载报告的URL。
report_id	字符串	报告的唯一ID。

合作伙伴报告API指引

报告API基础

获取客户账户端点

使用说明

查询参数

示例输出

输出详情

筛选器端点

使用说明

示例查询 (Python)

查询参数

示例输出

创建异步报告端点

使用说明

限制

示例查询 (Python)

查询参数

示例输出

获取报告状态端点

使用说明

示例查询 (Python)

查询参数

示例输出

输出详情