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

广告诊断 (Ad Diagnosis)

V1.1

loading

本节将为您介绍广告诊断 (Ad Diagnosis) 相关接口。该接口支持广告主获取已创建广告的效果分析及优化建议等诊断结果,便于广告主据此优化线上广告的投放策略。目前此接口暂时仅支持微信朋友圈广告的诊断功能,如需使用此接口,请联系对接的渠道运营同事线下申请权限。


广告诊断分析工具
全部接口
V1.1
loading

所属权限 Ads Management
请求地址 diagnosis/get
请求方法 get

全局参数

全局参数是指每一个接口都需要使用到的参数。详情参考,代码案例参考

参数名称 参数类型
access_token 授权令牌,完成 OAuth 2.0 授权后获得,参考授权认证章节
timestamp

当前的时间戳,单位为秒,允许客户端请求最大时间误差为 300 秒。

MarketingAPI 所使用的时间戳,若无特殊说明,均为秒级时间戳

MarketingAPI 所使用的时区为 GMT+8,例如当时间戳为 1494840119 时,表示 2017-05-15 17:21:59

nonce 随机字串标识,不超过 32 个字符,由调用方自行生成,需保证全局唯一性
fields get 接口增加 fields 字段,用于指定返回参数的字段列表,为选填字段。fields 取值范围为 get 接口返回的 list 中的字段。如不填写,则根据默认值进行返回

请求参数

参数仅适用于腾讯广告平台,暂不支持微信公众平台。
标有*的参数为必填项

名称 类型 描述
account_id*
integer 广告主 id,有操作权限的广告主 id
adgroup_id_list*
integer[] 广告组 id 列表,最多可写入 100 个广告组 id
每次写入的广告列表必须均为微信广告,或者均为非微信广告
数组最小长度 1,最大长度 100
time_range
struct 时间范围
仅当广告均为非微信广告时,此字段支持写入,且最多可选择日期为最近三天内的最长 24 小时区间。如果不填写,则默认返回最近两小时的数据。
微信广告暂不支持自定义查询时间范围,默认返回开始投放至今的所有数据
start_time*
integer 查询起止时间点对应的时间戳
最小值 0,最大值 9999999999
end_time*
integer 查询结束时间点对应的时间戳
最小值 0,最大值 9999999999

使用说明

  1. 1)非微信广告的诊断工具暂不支持批量,仅支持 1 秒调用 100 次。测试环节需与接口服务方重点联调验证。
  2. 2)当 site_set=SITE_SET_WECHAT(微信朋友圈广告,公众号广告暂不支持)时,仅当广告的曝光大于 500 且广告的状态为投放中或暂停等有效状态时,才会有结果返回,否则返回为空。

请求示例


curl -G 'https://api.e.qq.com/v1.1/diagnosis/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
-d 'account_id=<ACCOUNT_ID>' \
-d 'adgroup_id_list=[123,456]' \
-d 'time_range={"start_time":1564588800,"end_time":1564675200}' 
					

应答字段

名称 类型 描述
list
struct[] 返回数组列表
adgroup_id
integer 广告组 id
wechat_diagnosis_result_spec
struct 微信广告的诊断结论
仅微信广告会返回此字段
wechat_cost_diagnosis_result_spec
struct 微信广告的成本诊断结论
仅微信的 oCPA 广告会返回此字段
diagnosis_conclusion
string 综合评估结论
overall_cpc
integer 当日投放成本,单元分
history_cpc_spec_list
struct[] 近 30 天每日的成本曲线数据
仅当投放满 6 小时后,此字段才会有值
date
string 日期,日期格式:YYYY-mm-dd
actual_cpc
integer 实际达成成本,单元分
target_cpc
integer 目标出价,单元分
wechat_exposure_diagnosis_result_spec
struct 微信广告的曝光诊断结论
diagnosis_conclusion_spec
struct 整体曝光评估结果
time_range
struct 诊断周期使用的数据源起止时间,最多展示近 30 天的全量数据
start_time
integer 诊断数据起止时间点对应的时间戳
end_time
integer 诊断数据结束时间点对应的时间戳
diagnosis_score
integer 曝光竞争力得分(1-100 分)
10-20:很差,20-40:较差,50-60:一般,60-80:较好,80-100:很好
(接口返回一位小数)
same_industry_rank
integer 同行业排名百分比,超过同行业广告的占比
超过 80%-请继续保持; 40-80%:有较大提升空间; 10-40%:建议及时优化调整
targeting_diagnosis_conclusion_spec
struct 定向维度的曝光评估结果
targeting_diagnosis_score
integer 定向综合评估得分(1-100 分)
10-20:很差,20-40:较差,50-60:一般,60-80:较好,80-100:很好
根据流量整体环境分数综合计算得出,得分越高,定向环境越好,则越容易赢得曝光
(接口返回一位小数)
contract_occupied_score
integer 流量充足度(1-100 分)
竞价广告流量充足度主要受排期广告占量影响,排期广告占量越少,则竞价流量越充足,对应得分越高
contract_occupied_spec_list
struct[] 流量充足度明细数据,仅展示最近 3 天小时粒度的数据
date
string 日期,日期格式:YYYY-mm-dd
最多展示近 3 天数据
hour
integer 小时(0-23)
contract_occupied_score
integer 流量充足度(1-10 分)
compitition_score
integer 竞争激烈度情况(1-100 分)
具体为所选定向人群中各竞价广告之间的竞争情况,得分越高则胜出越困难
compitition_spec_list
struct[] 竞争激烈度明细数据
date
string 日期,日期格式:YYYY-mm-dd
最多展示近 3 天数据
hour
integer 小时(0-23)
compitition_score
integer 竞争激烈度(1-100 分)
conclusion
string 定向诊断结论
cost_diagnosis_conclusion_spec
struct 预算维度的曝光评估结果
cost_diagnosis_score
integer 预算分析得分(1-100 分)
根据受预算影响的余额控制过滤数据等综合计算得出,得分越高,预算对广告曝光速度影响越小
10-30:实时可用预算严重不足,严重影响广告消耗速度
30-60:实时可用预算不足,已经影响广告消耗速度
60-80:实时可用预算略有不足,轻微影响广告消耗速度
80-90:实时可用预算比较充足,几乎没有影响广告消耗速度
90-100:实时可用预算充足,没有影响广告消耗速度
balance
integer 账户当前余额,单位为分
ad_daily_budget
integer 该广告的日预算,单位为分
ad_realtime_available_budget
integer 广告实时可用预算,单位为分
该数据将根据实时账户余额、账户可用预算、计划可用预算、广告可用预算,以及当前的消耗情况实时调节
ad_cost
integer 广告今日消耗,单位为分
campain_daily_budget
integer 推广计划日预算,单位为分
campain_cost
integer 推广计划今日消耗,单位为分
campain_realtime_available_budget
integer 推广计划实时可用预算,单位为分
account_daily_budget
integer 账户日预算,单位为分
account_cost
integer 账户今日消耗,单位为分
account_realtime_available_budget
integer 账户实时可用预算,单位为分
conclusion
string 预算诊断结论
compitition_diagnosis_conclusion_spec
struct 竞争表现维度的曝光评估结果
compitition_diagnosis_score
integer 竞争表现综合评分(1-100 分)
10-20:很差
20-40:较差
40-60:一般
60-80:较好
80-100:很好
compitition_diagnosis_result
string 竞争表现综合结论
bid_amount_diagnosis_score
integer 出价竞争表现评估得分(1-100 分)
0-20:很差
20-40:较差
40-60:一般
60-80:较好
80-100:很好
bid_amount_diagnosis_conclusion
string 出价竞争表现综合结论
click_diagnosis_score
integer 点击竞争表现评估得分(1-100 分)
0-20:很差
20-40:较差
40-60:一般
60-80:较好
80-100:很好
click_diagnosis_conclusion
string 点击竞争表现综合结论
conversion_diagnosis_score
integer 转化竞争表现评估得分(1-100 分)
0-20:很差
20-40:较差
40-60:一般
60-80:较好
80-100:很好
conversion_diagnosis_conclusion
string 转化竞争表现综合结论
user_acceptance_diagnosis_score
integer 用户接受度竞争表现评估得分(1-100 分)
0-20:很差
20-40:较差
40-60:一般
60-80:较好
80-100:很好
user_acceptance_diagnosis_conclusion
string 用户接受度竞争表现综合结论
compitition_analysis_detail_spec_list
struct[] 竞争表现详细评估结果
date
string 日期,日期格式:YYYY-mm-dd
最多展示近 3 天数据
hour
integer 小时(0-23)
ad_user_acceptance
integer 用户接受度(单位:%),返回的数值为百分数
仅当 analysis_type=ANALYSIS_TYPE_AD(本广告数据)时,会返回此字段
ad_bid_amount
integer 本广告平均出价,单位为分
same_industry_bid_amount
integer 胜出广告平均出价,单位为分
win_over_ad_bid_amount
integer 同行业胜出广告平均出价,单位为分
ad_click
integer 本广告平均点击数
same_industry_click
integer 胜出广告平均点击数
win_over_ad_click
integer 同行业胜出广告平均点击数
ad_conversion
integer 本广告平均转化数
same_industry_conversion
integer 胜出广告平均转化数
win_over_ad_conversion
integer 同行业胜出广告平均转化数
page_info
struct 分页配置信息
page
integer 搜索页码,获取指定页数据,大于等于 1,小于等于实际总页数,若不传则视为 1
page_size
integer 一页获取的数据条数,1-100
total_number
integer 总条数
total_page
integer 总页数

应答示例

{
    "code": 0,
    "message": "",
    "message_cn": "",
    "data": {
        "list": [
            {
                "adgroup_id": "<ADGROUP_ID>",
                "wechat_diagnosis_result_spec": {
                    "wechat_cost_diagnosis_result_spec": {
                        "history_cpc_spec_list": []
                    },
                    "wechat_exposure_diagnosis_result_spec": {
                        "diagnosis_conclusion_spec": {
                            "time_range": {
                                "start_time": 1564588800,
                                "end_time": 1564675200
                            }
                        },
                        "targeting_diagnosis_conclusion_spec": {
                            "contract_occupied_spec_list": [],
                            "compitition_spec_list": []
                        },
                        "cost_diagnosis_conclusion_spec": [],
                        "compitition_diagnosis_conclusion_spec": {
                            "compitition_analysis_detail_spec_list": []
                        }
                    }
                }
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_number": 1,
            "total_page": 1
        }
    }
}

可视化调试工具