接口文档SDK业务专题开发者工具

广告数据洞察

通过本章节您将了解到 Marketing API 提供的广告数据洞察能力。

广告数据洞察接口为您提供广告投放后的数据报表和分析服务。我们的报表将涵盖推广帐号、推广计划、广告组、定向标签等多个层级的数据,并支持按日、小时的时间维度进行查询。所有报表数据均涵盖曝光量、点击量、费用、APP下载/转化/激活等常见的基础指标,如果需要平均点击单价(CPC)、平均千次展示价格(CPM)、平均转化率、平均转化成本等更多指标数据,您可以根据我们提供的基础数据自行计算得出。

依赖广告数据洞察相关接口提供的数据,您可以了解到不同广告在不同时段以及不同人群上的表现,并可以据此进一步优化广告投放。您可以通过以下章节了解广告数据洞察服务的具体功能:

    • 日报表:以天为维度查询各层级的报表数据;
    • 小时报表:以小时为维度查询各层级的报表数据;
    • 定向标签报表:以定向人群的性别、年龄、地域为维度查询报表数据。
    • 异步任务:异步获取全量报表数据。

除了了解 Marketing API 提供的数据报表维度和指标维度外,您可能还需要了解数据洞察中会涉及到的报表聚合规则以及返回数据条目。接下来,将为您介绍这两个规则。


聚合规则

不同类型的报表可选择聚合规则略有差异。首先,将分别介绍日报表、小时报表、定向标签报表可选择的聚合条件。

1、日报表默认按date(天)聚合,且不同level下支持的聚合条件如下:

    • 当level为ADVERTISER时,支持按date聚合。
    • 当level为CAMPAIGN时,支持按date、campaign_id聚合。
    • 当level为ADGROUP时,支持按date、adgroup_id、site_set 聚合。
    • 当level为AD时,支持按date、ad_id、site_set 聚合。
    • 当level为PRODUCT时,支持按date、product_type 、product_refs_id聚合。
    • 当level为CREATIVE_TEMPLAT时,支持按date、template_id、site_set聚合。

2、小时报表默认按hour(小时)聚合,且不同level下支持的聚合条件如下:

    • 当level为ADVERTISER时,支持按hour聚合;
    • 当level为CAMPAIGN时,支持按hour、campaign_id聚合;
    • 当level为ADGROUP时,支持按hour、adgroup_id 聚合;
    • 当level为AD时,支持按hour、ad_id 聚合;
    • 当level为PRODUCT 时,支持按hour、product_type 、product_refs_id聚合。

3、定向标签报表不同type下支持的聚合条件如下:

    • 当type为GENDER时,支持按gender聚合
    • 当type为AGE时,支持按age聚合
    • 当type为REGION时,默认按region_id聚合

聚合条件会影响最终的输出结果,接下来将通过几个示例说明各聚合条件的规则

1、日报表(daily_reports/get)

假设某帐号下共有10个广告组,且在2018/08/01-2018/08/11均有投放数据,若查询该帐号在2018/08/01-2018/08/11广告组维度(level = ADGROUP)的报表数据:

    • 选择按天聚合(GROUP BY date),则一共返回11条记录,各项指标为所有广告组在各天的综合指标,返回数据节点中的adgroup_id无意义;
    • 选择按广告组聚合(GROUP BY adgroup_id),则一共返回10条数据,各项指标为各广告组10天的综合指标,返回的数据节点中的date(天)无意义;
    • 选择同时按天以及广告组聚合(GROUP BY date,adgroup_id),则一共返回110条数据,各项指标为各广告组在各天的效果指标,返回的数据节点中的adgroup_id、date均有意义。

2、小时报表(hourly_reports/get)

假设某帐号下共有10个广告组,且在2018/08/01的24小时内均有投放数据,若查询该帐号在2018/08/01广告组维度(level = ADGROUP)的小时数据:

    • 选择按小时聚合(GROUP BY hour),则一共有24条数据,各项指标为所有广告组在每小时的综合指标,返回数据节点中的adgroup_id无意义;
    • 选择按广告组聚合(GROUP BY adgroup_id),则一共返回10条数据,各项指标为各广告组当天的综合指标,返回的数据节点中的hour(小时)无意义;
    • 选择同时按小时以及广告组聚合(GROUP BY hour,adgroup_id),则一共返回240条数据,各项指标为各广告组在各小时的效果指标,返回的数据节点中的adgroup_id、hour均有意义。

3、定向标签报表(targeting_tag_reports/get)

假设某帐号下共有10个广告组,且在2018/08/01-2018/08/11均有投放数据,若查询该帐号在2018/08/01-2018/08/11期间某广告组的性别数据:

      • 选择按天聚合(GROUP BY date),则一共返回11条记录,各项指标为该广告组在各天的综合指标,返回数据节点中的gender无意义;
      • 选择按性别聚合(GROUP BY gender),则一共返回2条数据,各项指标为该广告组11天分性别的综合指标,返回的数据节点中的date(天)无意义;
      • 选择同时按天以及性别聚合(GROUP BY date,gender),则一共返回22条数据,各项指标为该广告组分性别在这11天内的明细数据,返回的数据节点中的date、gender均有意义。

数据条目

返回的数据条目除了与聚合规则有关,还与数据。所有报表接口中,返回的数据将只包含至少有曝光量的条目数据,即报表返回中不会含有所有指标均为0的条目。

例如通过日报表接口查询某月1号到10号的帐号层级每日数据且按天聚合,而实际这个帐号只有1、2、3号有投放广告,则报表返回中只有3条记录,不会包含4号-10号这几天的条目。

使用限制

广告效果报表接口,除了需要受通用的接口调用频次限制外,还有以下限制(异步任务下载报表不受此限制):

  1. 1、分页获取的数据总条数限制为10000条,即 page*page_size 不能超过10000,超过后会被拦截。
  2. 2、10秒内查询匹配到的数据累计总条数限制为40000条,详细逻辑为:
    • 针对日报表(daily_reports/get)的每个层级(level)、小时报表(hourly_reports/get)的每个层级(level)、定向标签报表(targeting_tag_reports/get)每种类型(type)的每个层级(level),分别设置配额(quota)
    • 配额以10秒为周期,以周期内查询命中总数据量为计算依据
    • 周期内超出配额,将冻结对应请求的访问
    • 冻结时间根据本周期当前累计quota消耗进行计算,冻结时间 = 本周期剩余时长 + 向下取整( 本周期当前累计quota消耗 / 40000) * 10秒