需要授权
使用您定义的过滤条件和参数查询搜索流量数据。该方法会返回零个或零个以上的行,这些行按您定义的行键(维度)分组。您必须将日期范围定义为一天或多天。
如果日期是其中一个维度,结果列表中将忽略没有数据的所有日期。要了解哪些日期有数据,请针对感兴趣的日期范围发出不带过滤器(按日期分组)的查询。
结果按点击次数降序排序。如果两行的点击次数相同,则按任意方式对其进行排序。
如需了解如何调用此方法,请参阅 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 格式,且采用 PT 时间 (UTC - 7:00/8:00) 格式。必须小于或等于结束日期。该值包含在范围内。 | |
endDate |
string |
[必需] 所请求日期范围的结束日期,采用 YYYY-MM-DD 格式,以太平洋时间 (UTC - 7:00/8:00) 为单位。必须大于或等于开始日期。该值包含在范围内。 | |
dimensions[] |
list |
[可选] 0 个或多个用于对结果进行分组的维度。结果会按照您提供这些维度的顺序进行分组。您可以在 dimensionFilterGroups[].filters[].dimension 以及“日期”中使用任何维度名称。系统会对分组维度值进行合并,以便为每个结果行创建一个唯一键。如果未指定维度,所有值都将合并到一行。您可以按任意数量的维度进行分组,但同一个维度不能重复两次。示例:[国家/地区, 设备] | |
searchType |
string |
已废弃,请改用 type
|
|
type |
string |
[可选] 过滤以下类型的结果:
|
|
dimensionFilterGroups[] |
list |
[可选] 零个或零个以上要应用于维度分组值的过滤条件组。所有过滤条件组必须匹配,才能在响应中返回行。在一个过滤条件组中,您可以指定是必须匹配所有过滤条件,还是至少必须匹配一个过滤条件。 | |
dimensionFilterGroups[].groupType |
string |
此组中的所有过滤条件都必须返回 true(“and”),还是一个或多个过滤条件必须返回 true(尚不支持)。
可接受的值包括:
|
|
dimensionFilterGroups[].filters[] |
list |
[可选] [可选] 0 个或多个用于测试行的过滤条件。每个过滤条件均由维度名称、运算符和值组成。长度上限为 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 对实际数据调用此方法,并查看响应。