需要授权
使用您定义的过滤条件和参数查询搜索流量数据。该方法会返回按您定义的行键（维度）分组的零个或零个以上的行。您必须将日期范围定义为一天或多天。
如果日期是其中一个维度，结果列表中将省略没有数据的所有日期。要了解哪些日期有数据，请针对感兴趣的日期范围发出不带按日期分组的过滤条件的查询。
结果按点击次数降序排列。如果两行的点击次数相同，则会以任意方式进行排序。
如需了解如何调用此方法，请参阅 python 示例。
此 API 受 Search Console 内部限制的约束，并不保证返回所有数据行，而是返回热门数据行。
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
"startDate": "2015-04-01",
"endDate": "2015-05-01",
"dimensions": ["country","device"]
}请求
HTTP 请求
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
参数
| 参数名称 | 值 | 说明 |
|---|---|---|
| 路径参数 | ||
siteUrl |
string |
Search Console 中定义的资源网址。示例：http://www.example.com/（针对网址前缀资源）或 sc-domain:example.com（针对网域资源）
|
授权
此请求需要获得以下至少一个范围的授权（详细了解身份验证和授权）。
| 范围 |
|---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
请求正文
在请求正文中，请按以下结构提供数据：
{
"startDate": string,
"endDate": string,
"dimensions": [
string
],
"type": string,
"dimensionFilterGroups": [
{
"groupType": string,
"filters": [
{
"dimension": string,
"operator": string,
"expression": string
}
]
}
],
"aggregationType": string,
"rowLimit": integer,
"startRow": integer
}
| 属性名称 | 值 | 说明 | 备注 |
|---|---|---|---|
startDate |
string |
[必需] 所请求日期范围的开始日期，采用 YYYY-MM-DD 格式，格式为太平洋时间 (UTC - 7:00/8:00)。必须少于或等于结束日期。此值包含在范围内。 | |
endDate |
string |
[必需] 所请求日期范围的结束日期，采用 YYYY-MM-DD 格式，以葡萄牙时间 (UTC - 7:00/8:00) 表示。必须晚于或等于开始日期。此值包含在范围内。 | |
dimensions[] |
list |
[可选] 结果分组依据的零个或多个维度。结果会按照您提供这些维度的顺序分组。您可以在 dimensionFilterGroups[].filters[].dimension 以及“日期”中使用任何维度名称。系统会合并分组维度值，以便为每个结果行创建一个唯一键。如果未指定维度，所有值将合并到一行中。分组依据的维度数量没有限制，但您不能按同一维度分组两次。示例：[国家/地区, 设备] | |
searchType |
string |
已废弃，请改用 type
|
|
type |
string |
[可选] 过滤出以下类型的结果：
|
|
dimensionFilterGroups[] |
list |
[可选] 要应用于维度分组值的零个或零个以上的过滤条件组。所有过滤条件组必须匹配，系统才会在响应中返回行。在单个过滤器组中，您可以指定是否必须匹配所有过滤器，还是至少有一个过滤器必须匹配。 | |
dimensionFilterGroups[].groupType |
string |
此组中的所有过滤条件都必须返回 true（“and”），还是必须返回 true（尚不支持）。
可接受的值为：
|
|
dimensionFilterGroups[].filters[] |
list |
[可选] 要针对该行测试零个或多个过滤条件。每个过滤器均由维度名称、运算符和值组成。长度上限为 4096 个字符。示例：country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
此过滤器应用到的维度。您可以按此处列出的任何维度进行过滤，即使您并未按该维度进行分组。
可接受的值：
|
|
dimensionFilterGroups[].filters[].operator |
string |
[可选] 指定的值必须与该行的维度值如何匹配（或不匹配）。
可接受的值为： |
|
dimensionFilterGroups[].filters[].expression |
string |
要匹配或排除的过滤器值，具体取决于运算符。 | |
aggregationType |
string |
[可选] 数据的汇总方式。如果按资源汇总，系统会汇总同一资源的所有数据；如果按网页汇总，则所有数据都会按规范 URI 汇总。如果您要按网页过滤或分组，请选择“自动”；否则，您可以按资源或按网页进行汇总，具体取决于您希望如何计算数据；请参阅帮助文档，了解不同网站的数据计算方式与按网页计算方式的不同。 注意：如果您按网页分组或过滤，则无法按资源汇总。 如果您指定除 auto 以外的任何值，则结果中的聚合类型将与请求的类型匹配，或者如果您请求无效类型，则会收到错误。如果请求的汇总类型无效，该 API 绝不会更改您的汇总类型。 可接受的值为：
|
|
rowLimit |
integer |
[可选；有效范围为 1–25,000；默认值为 1,000] 要返回的行数上限。要对结果进行分页，请使用 startRow 偏移量。 |
|
startRow |
integer |
[可选；默认值为 0] 响应中第一行的索引（从零开始）。必须是非负数。如果 startRow 超出了查询的结果数，则响应将是一个成功响应，其中为零行。 |
|
dataState |
string |
[可选] 如果设为“all”（不区分大小写），数据将包含最新数据。 如果为“final”（不区分大小写）或省略此参数，则返回的数据将仅包含最终数据。 |
响应
系统会根据请求中指定的维度对结果进行分组。具有同一组维度值的所有值都会归在一行中。例如，如果您按国家/地区维度进行分组，则与“usa”对应的所有结果会归为一组，“mdv”的所有结果则会归为一组，以此类推。如果您按国家/地区和设备分组，则会对“美国, 平板电脑”的所有搜索结果分组，对“美国, 移动设备”的所有搜索结果分组，以此类推。请参阅“搜索分析”报告文档，详细了解点击次数、展示次数等的计算方式及其含义。
结果按点击次数降序排序，除非您按日期分组，在这种情况下，结果按日期升序排序（由旧到新，最后）。如果两行之间存在旗鼓相当的情况，则排序顺序是任意的。
请参阅请求中的 rowLimit 属性，了解可以返回的值的最大数量。
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}
| 属性名称 | 值 | 说明 | 备注 |
|---|---|---|---|
rows[] |
list |
按查询中指定的顺序按键值分组的行列表。 | |
rows[].keys[] |
list |
相应行的维度值列表，并根据请求中的维度进行分组（按请求中指定的顺序）。 | |
rows[].clicks |
double |
该行的点击次数。 | |
rows[].impressions |
double |
该行的展示次数。 | |
rows[].ctr |
double |
相应行的点击率 (CTR)。值的范围是 0 到 1.0（含 0 和 1.0）。 | |
rows[].position |
double |
在搜索结果中的平均排名。 | |
responseAggregationType |
string |
结果的汇总方式。请参阅帮助文档，了解不同网站的数据计算方式与按网页统计的方式不同。
可接受的值为：
|
试试看！
请使用下面的 API Explorer 对实时数据调用此方法并查看响应。