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
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            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 中的任何维度名称,以及“date”和“hour”。系统会组合分组维度值,为每个结果行创建唯一键。如果未指定维度,所有值都将合并到一行中。您可以按任意数量的维度进行分组,但不能按同一维度分组两次。示例:[country, device]
searchType string 已弃用,请改用 type
type string [可选] 将结果过滤为以下类型:
  • “discover”:Google 探索结果
  • “googleNews”:来自 news.google.com 以及 Android 和 iOS 版 Google 新闻应用的结果。不包含 Google 搜索中“新闻”标签页的结果。
  • “news”:Google 搜索中“新闻”标签页内的搜索结果。
  • “image”:Google 搜索中“图片”标签页内的搜索结果。
  • “video”:视频搜索结果
  • "web":[默认] 将结果过滤为 Google 搜索中的合并(“全部”)标签页。不包括 Google 探索或 Google 新闻结果。
  • “webMultimodal”:来自 Google 智能镜头、Android 上的“圈定即搜”功能以及 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”分组依据的查询。帮助文档中也提供了值和说明的完整列表。
  • “brandedClassification”:根据指定的含品牌词的搜索查询分类过滤结果(仅支持“equals”运算符)。 在同一请求中,按“brandedClassification”分组依据或过滤不能与“query”过滤条件结合使用。提供 2026 年 2 月 21 日及之后的数据,并且仅适用于具有足够查询量和展示量的顶级资源(请参阅含品牌词的搜索查询公告)。 支持的值:
    • 品牌
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [可选] 您指定的值必须如何与行的维度值匹配(或不匹配)。

可接受的值包括:
  • “contains”:行值必须包含或等于您的表达式(不区分大小写)。
  • “equals”:[默认] 您的表达式必须与行值完全一致(对于网页和查询维度,区分大小写)。
  • “notContains”:行值不得包含您的表达式,无论是作为子字符串还是作为(不区分大小写的)完全匹配项。
  • “notEquals”:表达式不得与行值完全相同(对于网页和查询维度,区分大小写)。
  • “includingRegex”:必须匹配的 RE2 语法正则表达式。
  • “excludingRegex”:不得匹配的 RE2 语法正则表达式。
dimensionFilterGroups[].filters[].expression string 要匹配或排除的过滤条件的值,具体取决于运算符。
dimensionFilterGroups[].filterLists[] list [可选] 零个或多个多值维度过滤条件,用于针对行进行测试。 filters[] 只能匹配每个条目的单个值,而 filterLists[] 允许在单个过滤条件中针对单个维度的多个完全匹配值进行匹配。如果某行中指定 dimension 的值等于提供的任何 expressions,则该行与过滤条件列表匹配。请注意,单个请求不能同时在 filters 和 filterLists 中对同一维度进行过滤。
dimensionFilterGroups[].filterLists[].dimension string [必需] 此过滤条件列表适用的维度。

可接受的值包括:
  • “country”:使用 3 字母国家/地区代码 (ISO 3166-1 alpha-3) 针对指定国家/地区进行过滤。
  • “device”:根据指定的设备类型(DESKTOP、MOBILE、TABLET)进行过滤。
dimensionFilterGroups[].filterLists[].expressions[] list [必需] 要过滤的值列表 (string)。
aggregationType string

[可选] 数据的汇总方式。如果按资源汇总,则会汇总同一资源的所有数据;如果按网页汇总,则会按规范 URI 汇总所有数据。如果您按网页过滤或分组,请选择“auto”;否则,您可以按资源或按网页汇总,具体取决于您希望如何计算数据;请参阅帮助文档,了解按网站和按网页计算数据的不同方式。

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

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

可接受的值包括:
  • “auto”:[默认] 让服务决定适当的汇总类型。
  • “byNewsShowcasePanel”:按“新闻编辑精选”面板汇总值。 此标记必须与 NEWS_SHOWCASE searchAppearance 过滤条件以及 type=discover 或 type=googleNews 结合使用。如果您按网页分组、按网页过滤或过滤到其他 searchAppearance,则无法按 byNewsShowcasePanel 汇总。
  • “byPage”:按 URI 汇总值。
  • “byProperty”:按属性汇总值。type=discover 或 type=googleNews 不支持
rowLimit integer [可选;有效范围为 1–25,000;默认值为 1,000] 要返回的最大行数。如需对结果进行分页,请使用 startRow 偏移量。
startRow integer [可选;默认值为 0] 响应中第一行的索引(从 0 开始)。必须是非负数。如果 startRow 超过查询结果的数量,则响应将是包含零行的成功响应。
dataState string [可选] 如果为“all”(不区分大小写),则数据将包含新数据。 如果值为“final”(不区分大小写)或省略此参数,则返回的数据将仅包含最终数据。 如果为“hourly_all”(不区分大小写),则数据将包含每小时细分数据。这表示每小时数据包含部分数据,应在按 HOUR API 维度分组时使用。

响应

结果会根据请求中指定的维度进行分组。具有相同维度值集的所有值都将归入同一行。例如,如果您按国家/地区维度分组,则“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(含边界值)。
rows[].position double 在搜索结果中的平均排名。
responseAggregationType string 结果的汇总方式。请参阅帮助文档,了解按网站和按网页计算数据有何不同。

可接受的值包括:
  • “auto”
  • “byPage”:结果按网页汇总。
  • “byProperty”:结果按资源汇总。
metadata object

一个可能随查询结果一起返回的对象,用于提供有关数据状态的上下文。

当您请求近期数据(对 dataState 使用 all 或 hourly_all)时,返回的部分行可能代表不完整的数据,这意味着数据仍在收集和处理中。此元数据对象可帮助您准确识别此过程的开始和结束时间。

此对象中提供的所有日期和时间均采用 America/Los_Angeles 时区。

此对象中返回的具体字段取决于您在请求中对数据进行分组的方式:

  • first_incomplete_date (string):仍在收集和处理数据的第一个日期,以 YYYY-MM-DD 格式(ISO-8601 扩展本地日期格式)显示。

    仅当请求的 dataState 为 all、数据按 date 分组依据,且请求的日期范围包含不完整的数据点时,系统才会填充此字段。

    first_incomplete_date之后的所有值可能仍会有明显变化。

  • first_incomplete_hour (string):仍在收集和处理数据的第一个小时,以 YYYY-MM-DDThh:mm:ss[+|-]hh:mm 格式(ISO-8601 扩展偏移日期时间格式)显示。

    仅当请求的 dataState 为 hourly_all、数据按 hour 分组依据且请求的日期范围包含不完整的数据点时,系统才会填充此字段。

    first_incomplete_hour之后的所有值可能仍会有明显变化。

试试看!

使用下面的 API Explorer 对实际数据调用此方法,然后查看响应。