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

广告诊断分析工具
全部接口
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
int64 广告组 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
        }
    }
}

可视化调试工具