Search Analytics: query

需要授权

使用您定义的过滤条件和参数查询搜索流量数据。该方法会返回按您定义的行键(维度)分组的零个或零个以上的行。您必须将日期范围定义为一天或多天。

如果日期是其中一个维度,结果列表中将忽略所有没有数据的日期。要了解哪些日期有数据,请针对感兴趣的日期范围,发出不带过滤器(按日期分组)的查询。

结果按点击次数降序排序。如果两行的点击次数相同,则按任意方式排序。

请参阅 python 示例,了解如何调用此方法。

此 API 受 Search Console 内部限制的约束,并不能保证返回所有数据行,而是返回最重要的数据行。

查看可用数据量限制

JSON POST 示例:
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 [可选] 结果分组依据的零个或多个维度。结果会按照您提供这些维度的顺序进行分组。您可以在 dimensionFilterGroups[].filters[].dimension以及“日期”中使用任何维度名称。系统会合并分组维度值,为每个结果行创建一个唯一键。如果未指定维度,所有值都将合并到一行。分组依据的维度数量没有限制,但不能按同一维度分组两次。示例:[国家/地区, 设备]
searchType string 已废弃,请改用 type
type string [可选] 按以下类型过滤结果:
  • discover”:Google 探索结果
  • googleNews”:来自 news.google.com 以及 Android 和 iOS 版 Google 新闻应用的搜索结果。不包括 Google 搜索中“新闻”标签页中的结果。
  • news”:来自 Google 搜索“新闻”标签页的搜索结果。
  • image”:来自 Google 搜索“图片”标签页的搜索结果。
  • video”:视频搜索结果
  • "web": [默认] 在 Google 搜索中将结果过滤到合并后的(“全部”)标签页中。不包括 Google 探索或 Google 新闻搜索结果。
dimensionFilterGroups[] list [可选] 零个或零个以上要应用于维度分组值的过滤条件组。所有过滤条件组必须匹配,响应中才会返回相应的行。在单个过滤条件组中,您可以指定是必须匹配所有过滤条件,还是必须匹配至少一个过滤条件。
dimensionFilterGroups[].groupType string 此组中的所有过滤条件都必须返回 true(“and”),还是一个或多个必须返回 true(尚不支持)。

可接受的值为:
  • "and>:对于过滤器组,组中的所有过滤器都必须返回 true。必须为 true。
dimensionFilterGroups[].filters[] list [可选] 要针对相应行测试零个或多个过滤条件。每个过滤条件均由维度名称、运算符和值组成。长度上限为 4096 个字符。示例:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string 此过滤器应用到的维度。您可以按此处列出的任何维度进行过滤,即使您没有按该维度分组也是如此。

可接受的值:
  • country”:根据指定的国家/地区进行过滤,按照由 3 个字母的国家/地区代码表示 (ISO 3166-1 alpha-3)。
  • device”:根据指定的设备类型过滤结果。支持的值:
    • 桌面设备
    • 移动设备
    • 平板电脑
  • page”:针对指定的 URI 字符串进行过滤。
  • query”:针对指定的查询字符串进行过滤。
  • searchAppearance”:针对特定搜索结果功能进行过滤。如需查看可用值的列表,请运行按“searchAppearance”分组的查询。
dimensionFilterGroups[].filters[].operator string [可选] 您指定的值必须与该行的维度值匹配(或不匹配)。

可接受的值为:
  • contains”:行值必须包含或等于您的表达式(不区分大小写)。
  • "equals": [默认] 您的表达式必须完全等于行值(对于网页维度和查询维度,区分大小写)。
  • notContains”:行值不得包含子字符串或(不区分大小写)完全匹配形式的表达式。
  • notEquals”:您的表达式不得与行值完全相同(对于网页维度和查询维度,区分大小写)。
  • includingRegex”:必须匹配的 RE2 语法正则表达式。
  • excludingRegex”: RE2 语法正则表达式,不得匹配。
dimensionFilterGroups[].filters[].expression string 要匹配或排除的过滤器值,具体取决于运算符。
aggregationType string

[可选] 数据的汇总方式。如果按资源汇总,系统会汇总同一资源的所有数据;如果按网页汇总,则所有数据都会按规范 URI 进行汇总。如果您选择按网页过滤或分组,请选择“自动”;否则,您可以按资源或按网页进行汇总,具体取决于您想要的数据计算方式;请参阅帮助文档,了解不同网站的数据计算方式与按网页计算方式的不同。

注意:如果按网页分组或过滤,则无法按资源汇总。

如果您指定除 auto 以外的任何值,结果中的聚合类型将与请求的类型匹配,或者如果您请求无效类型,则会收到错误。如果请求的汇总类型无效,该 API 绝不会更改汇总类型。

可接受的值包括:
  • "auto": [默认] 让该服务决定适当的汇总类型。
  • byNewsShowcasePanel”:按 Google 新闻编辑精选面板聚合值。此过滤器必须与 NEWS_SHOWCASE searchAppearance 过滤器以及 type=discovertype=googleNews 结合使用。 如果您按网页分组、按网页过滤或过滤出另一个 searchAppearance,则无法按 byNewsShowcasePanel 进行汇总。
  • byPage”:按 URI 汇总值。
  • byProperty”:按属性汇总值。不支持 type=discovertype=googleNews
rowLimit integer [可选;有效范围为 1–25,000;默认值为 1,000] 要返回的行数上限。如需对结果进行分页,请使用 startRow 偏移。
startRow integer [可选;默认值为 0] 响应中第一行的索引(从零开始)。必须是非负数。如果 startRow 超出了查询的结果数,则响应将会返回零行的成功响应。
dataState string [可选] 如果为“all”(不区分大小写),数据将包含最新数据。如果为“ final”(不区分大小写)或省略此参数,则返回的数据将只包含最终数据。

响应

系统会根据请求中指定的维度对结果进行分组。系统会将具有相同维度值组的所有值划分到一行中。例如,如果您按“国家/地区”维度进行分组,则“usa”对应的所有结果会归为一组,“mdv”对应的所有结果会归为一组,依此类推。如果您按国家/地区和设备分组,则系统会对“usa,以平板电脑”的所有搜索结果进行分组,并将与“usa, mobile”对应的所有结果分组,以此类推。请参阅“搜索分析”报告文档,详细了解点击次数、展示次数等指标的计算方式及其含义。

结果按点击次数降序排序,除非您按日期分组,在这种情况下,结果是按日期升序排序(由旧到新、由新到旧)。如果两行之间存在旗鼓相当的情况,则排序顺序是任意的。

请参阅请求中的 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 结果的汇总方式。请参阅帮助文档,了解网站与网页不同数据的计算方式。

可接受的值为:
  • "auto"
  • byPage”:结果按网页汇总。
  • byProperty”:结果按资源汇总。

试试看!

请使用下面的 API Explorer 对实时数据调用此方法并查看响应。