搜狗首页  |   服务首页  |   客服热线:010-56898080

API参考  |  报表服务

报表服务 (ReportService)

通过 ReportService ,您可以获取推广效果的详细报表。由于产生报表需要一定的时间,我们采用了异步的方式对报表进行处理。您首先需要通过 getReportId() 方法获得一个字符串类型的 reportId ,然后通过 pull 的方式轮询调用 getReportState() 方法检查报表是否产生。待产生后,则可调用 getReportPath() 方法获取报表的下载地址。根据该地址即可下载您所需要的报表。 报告 id 采用 <32 位 16 进制数 > 的取值形式,例如: 8e7e3f2d84a19c5df1415957434b2bd8

数据类型

接口描述

getReportId

方法说明:求绩效数据报告
输入信息: getReportIdRequest :绩效数据的查询条件,只有一个 ReportRequestType 对象 ,该对象说明如下 :

属性名 类型 说明 限制
performanceData String[] 指定绩效数据 必填
取值范围: cost cpc click position
cost: 消耗
consumePercent: 消耗占比
cpc: 点击均价
click: 点击数
clickPercent: 点击占比
position: 关键词平均排名
startDate dateTime 统计开始时间,格式参考:
2010-08-01T00:00:00.000
必填
endDate dateTime 统计结束时间,格式参考:
2010-08-17T23:59:59.000
必填
idOnly Boolean 是否只需要 id 选填;默认为 false
取值范围:
true :只获取 id
false :既获取 id 也获取字面
levelOfDetails Integer 统计粒度 选填;默认值为1;
下列取值范围仅用于地域报告:
1:账户范围
2:计划范围
Opt Opt 针对特定的报告类型设置特定的统计范围 无效属性
format Integer 报告文件格式 选填,默认值为 1 ;
1 : csv 格式(gzip压缩)
reportType Integer 报告类型 必填;
说明:分钟级报告需要开发
1 :账户报告(支持分时及分钟级报告)
2 :计划报告(支持分时及分钟级报告)
3 :推广组报告 (支持分时及分钟级报告)
4 :创意报告
5 :关键词报告 (cpcid) 报告(支持分时及分钟级报告)
6 :搜索词报告
13 :地域报告
14 :二级地域报告
statRange Integer 统计范围 选填,默认值为 1 ;
1 :账户范围
2 :计划范围
3 :推广组范围
4 :创意范围
5 :关键词 (cpcid) 范围
注意:统计范围不能细于当前的统计粒度,例如统计粒度为计划,则统计范围不能细到推广组
statIds Long[] 统计范围下的 id 集合。根据 StatRange 的不同类型填写不同 id 选填,默认 NULL ,表示统计范围为全账户
statRange 为 2 时填写计划 id;
statRange 为 3 时填写推广组 id;
statRange 为 4 时填写创意 id;
statRange 为 5 时填写关键词 调取指定分钟级关键词时,数组内关键词个数为200;
statRange 为 6 时填写附加样式id;
unitOfTime Integer 统计时间单位 选填,默认值为 1
取值范围:
1 :日报
2 :周报
3 :月报 (搜索词报告不支持月报)
4 :分时报告(仅支持账户报告、推广计划报告、推广组报告、关键词报告)
5:分钟级报告(仅支持当天的账户报告、推广计划报告、推广组报告、关键词报告)
regions Integer[] 投放地区列表 选填,默认为0
取值范围:
(选填)默认全部区域,取值范围参考地域代码;
地域代码个数上限15;
该字段仅针对于指定关键词报告;
showLocateMode Integer 展现定位方式 选填,默认为0
取值范围:
0:否
1:是
仅用于地域数据报告;

返回信息: getReportIdResponse :含有本次请求所返回的 reportId.

属性名 类型 说明 限制
reportId String 生成的报告 ID ID 为一串 MD5 值,格式为 32 位 16 进制数标示,例如 8e7e3f2d84a19c5df1415957434b2bd8

getReportState

方法说明:查询报告是否生成
输入信息: getReportStateRequest

属性名 类型 说明 限制
reportId String 请求的报告 ID

返回信息: getReportStateResponse:

属性名 类型 说明 限制
isGenerated Integer 报告生成状态 1: 已完成
0: 处理中
-1:报表生成异常

附加说明:在获取 Report 下载 url 前,请调用此方法。待确认报表已生成时,再获取下载的 url 。
getReportPath

方法说明:获取报告下载地址
输入信息: getReportPathRequest

属性名 类型 说明 限制
reportId String 报告 ID

返回信息: getReportPathResponse

属性名 类型 说明 限制
reportFilePath String 下载地址


报表限制

报告格式:

报告采用CSV格式,分隔符为逗号

数据容量:

建议返回的文件不要超过 10 万条数据

时间跨度:

报告时间跨度不得超过1年
搜索词历史报告最多只提供最近92天的数据,搜索词实时报告可以获取今天的累计数据(不包含一小时内的数据,且不可跨天取)
关键词报告可提供近一年的数据,但其中的关键词平均排名这一列最多只提供最近30天的数据
关键词报告(含有展现无点击数据)可提供近三个月的数据,时间跨度不得超过30天
分时报告最多只提供最近92天的数据,统计时间跨度不超过31天

在请求报表时,请注意控制参数值,尤其是起止时间参数。如果您账户数据比较多,起止时间又过大,可能会导致报表无法正确生成。如果在正确获得报表 id 后,超过 5 分钟无法获得报表,说明您的参数的设置不合适

分钟级报告限制:

分钟级报告只支持查询当天的数据,时间跨度不得超过半个小时,有一个小时的延迟,除此之外还有一个总体限制条件:
statIds个数*platform类别* regions区域个数*时间段<=500000
公式解释:
Platform选择0时,则计算时platform类别取值为2;
时间段是指起始时间到结束时间之间的分钟个数;
Regions该字段仅针对于指定关键词数据报告时使用,若不填,则默认全部地域地域;

数据实时性:

当天九点之后可以获取昨天的数据

报告数量:

您的报告请求数量不受限制

报告有效期:

1 周