欢迎使用 Singular 的报告 API，该 API 可提供有关营销活动的汇总统计数据，您可以将这些数据导入内部 BI 系统或营销绩效仪表板。

本指南介绍了 Singular Reporting API、如何理解您的用例以及如何开始运行查询。

请先阅读本指南，然后查看报告API 参考以 了解技术细节。

入门：了解使用案例

Singular从不同来源收集和综合数据（建议阅读《了解Singular报告数据》一书进行深入了解）。

使用报告 API 时，您可以选择是否要查看以下数据：

• 来自合作伙伴广告网络和代理商的 汇总数据，如广告活动成本；
• 来自归因追踪器/MMP 的 汇总数据，您可以将其输入 BI 系统，并根据需要与网络数据连接；
• 或组合数据，这是 Singular 将网络数据和跟踪器数据巧妙结合的结果，可让您以尽可能高的粒度分析投资回报率。

虽然所有查询都通过相同的端点（创建异步报告）运行，但它们在查询中包含的字段有所不同。

要开始使用，请先了解您想从 API 中获得什么：

您的使用案例：	请看：
您使用 Singular从所有广告网络和代理机构收集广告活动数据。 您希望获得有关成本和运行率的数据。	查询网络数据
您使用Singular 归因服务或为第三方归因跟踪器设置了数据连接器。 您希望获取转化率和收入等跟踪数据，并将其输入 BI 平台或用于分析。 如果您要将追踪器数据与广告网络数据（如营销活动成本）结合起来计算 ROAS，您计划使用自己的工具来完成这项工作。	分别查询跟踪器数据和网络数据
您使用 Singular 归因服务，或为第三方归因跟踪器设置了数据连接器。 您希望利用 Singular 的现成逻辑，以尽可能高的粒度连接网络数据和追踪器数据。	查询组合数据

通过报告 API 获取的数据类型

查询网络数据

网络数据包括从您在 Singular 中设置的所有广告网络中获取的营销活动统计数据。它不包括来自归因追踪器的数据（如果您在 Singular 中设置了归因追踪器）。

例如，你可以运行查询，查看给定日期范围内每个广告系列（adn_campaign_id）的成本（adn_cost）。

网络数据的可用字段

有关每个字段的说明，请参阅 "度量和维度"页面。

分别查询追踪器数据和网络数据

您可以使用应用程序接口获取追踪器数据--来自Singular归因服务或您在Singular中设置的第三方归因追踪器（如Appsflyer或Google Analytics）的统计数据。

例如，您可以运行查询，查看给定日期范围内每个营销活动（tracker_campaign_id）的点击次数（tracker_clicks）和安装次数（tracker_installs）。跟踪器统计数据还包括安装后事件和收入。

在对跟踪器数据进行查询后，您可以将其与网络数据结合起来 ，计算营销活动 CPI 或 ROI。

不过，运行合并报告通常更容易获得相同的结果。

跟踪器数据的可用字段

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

查询组合数据

您可以使用应用程序接口运行网络和跟踪器组合查询，从而显示您的营销活动成本和收入或其他营销活动绩效 KPI。

这种类型的查询使用基于跟踪器和网络数据的特殊维度和指标，但涉及额外的幕后逻辑，详情如下。

组合查询有什么作用？

1. 它将 网络统计（如成本）和跟踪器统计（如安装和收入）包含在同一个查询中。

2. 智能维度有助于尽可能将网络数据和跟踪器数据合并到同一行中。

   Singular 的 "组合 "或 "统一 "维度基于网络和跟踪器数据。Singular 会对它们进行处理，以纠正常见的数据不匹配问题，并确保您能以尽可能高的粒度看到组合数据。

   例如，跟踪器中特定广告系列的名称可能与从广告网络中提取的广告系列名称略有不同。因此，如果运行跟踪器报告和网络报告并将结果连接起来，可能会得到广告系列的不同行，其中一行是网络统计信息，另一行是跟踪器统计信息。但如果运行合并报告（使用统一的广告系列名称维度），Singular 会确保您仍能在同一行中获得广告系列的网络统计信息和跟踪器统计信息。

3. 在每种情况下，智能、可定制的指标都会从正确的来源获取数据。

   在网络和跟踪器都提供相同统计数据的情况下，例如，在给定的日期范围内每个营销活动的安装次数，组合指标为您提供单一的真相来源，根据标准的行业用法智能地选择跟踪器统计数据或网络统计数据。

   例如，custom_installs 指标包含来自跟踪器的安装次数，除非是自归属网络（SAN），如 Facebook 或 Twitter，在这种情况下，网络统计更为重要，而 custom_installs 则包含网络指标。

   如果 Singular 的默认选择不适合你的具体情况，你可以让 Singular 为你重新配置特定指标。

   注意： 自定义指标不适用于创意细分。请选择网络指标或跟踪指标。

如果我需要知道指标的来源怎么办？

您可能想知道每个营销活动的每个指标的确切来源，例如，如果您想找到网络指标与跟踪指标之间的重大差异并排除故障。

在这种情况下，您可以将网络指标（请参阅 "网络数据的可用字段"）和跟踪器指标（请参阅 "跟踪器数据的可用字段"）添加到合并报告中。例如，调出所有三个安装指标：custom_installs、adn_installs、tracker_installs。

这样，您就可以使用 custom_installs 作为关键绩效指标，同时还能看到 adn_installs 和 tracker_installs 之间是否存在显著差异。

组合数据的可用字段

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

总结：您可以使用哪些类型的数据？

	我使用 Singular
	分析 + Singular 归因	仅分析，但我设置了 Singular 从我的第三方跟踪器中提取数据	仅从我的广告网络提取数据
网络数据	可用	可用	可用
跟踪数据	可用	可用	-
综合字段	可用	适用于自归属网络（无创意细分）	-

如何查询报告 API

确定要查询的数据类型，并列出感兴趣的具体指标和维度后，下面介绍如何使用报告 API。

运行基本查询

1	查询 "创建异步报告"端点（请参阅端点参考），指定您选择的指标和维度。 这将生成一个异步报告查询，并返回一个报告 ID。
2	使用报告 ID，查询 "获取报告状态"API 端点（请参阅 "端点参考"），查看报告何时完成运行。 报告完成后，"获取报告状态 "端点会返回一个报告 URL。
3	从报告 URL 下载报告。

运行每日报告

Singular 中的数据每日更新。通常情况下，您需要每天从 Singular 中提取数据，包括

• 昨天的数据
• 网络可能已经更新的历史数据。

在常规的每日报告中，我们建议使用以下时间窗口提取历史数据：

查询类型	推荐时间窗口
网络数据	7 天前。
跟踪数据或组合数据	与最长队列时间一样长的时间段。例如，如果您有 30 天的队列，则查询 30 天前的数据。如果不提取任何队列数据（如收入），通常提取 7 天前的数据就足够了。

检查数据可用性

您可以使用 "数据可用性状态"（Data Availability Status）端点来检查每个数据连接器在给定日期是否有来自该连接器的数据，以及上次刷新该数据是在什么时候。

这个端点最常见的用途是检查 每个数据连接器昨天的数据 是否 可用。这样，如果所有数据连接器都准备就绪，就可以开始为所有数据运行报告。如果只有部分数据连接器有数据，而其他数据连接器还没有，你可以选择是等待所有数据连接器都完成，还是在每个数据源的数据可用时运行报告。(要在创建同步报告（Create Async Report）中对单个数据连接器运行报告，请按数据连接器 ID 过滤报告）。

请注意，Singular 不建议在同一查询中对多个数据连接器/数据源运行报告。

检查数据的新鲜度

要查看 Singular 中网络数据的最新情况，请在报告查询中包含data_connector_timestamp_utc维度。

该维度包括 Singular开始从数据连接器中提取数据的日期和时间（无论在 Singular 数据库中摄取、处理和保存数据花费了多长时间）。

数据时间戳的用例包括

• 如果您遇到 Singular 报告与网络仪表板中的数据不一致的情况
• 如果你正在使用 Singular 数据目的地（ETL）将数据从 Singular 拉入 BI 平台，并希望查看 Singular 是否有更新的数据