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 格式，以太平洋时间 (UTC - 7:00/8:00) 为准。不得迟于结束日期。此值包含在范围内。
endDate string [必需] 所请求日期范围的结束日期，采用 YYYY-MM-DD 格式，以太平洋时间 (UTC - 7:00/8:00) 为准。不得早于开始日期。此值包含在范围内。
dimensions[] list [可选] 用于对结果进行分组的零个或多个维度。结果会按您提供这些维度的顺序进行分组。您可以在 dimensionFilterGroups[].filters[].dimension 中使用任何维度名称，以及“date”和“hour”。系统会组合分组维度值，为每个结果行创建一个唯一键。如果未指定任何维度，所有值将合并为一行。您可以按任意数量的维度进行分组，但不能按同一维度进行两次分组。示例：[国家/地区、设备]
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 时，过滤条件组 t才返回 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”：根据指定的设备类型过滤结果。支持的值：
    • DESKTOP
    • 移动设备
    • 平板电脑
  • “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=discover 或 type=googleNews 结合使用。 如果您按网页进行分组、按网页进行过滤或过滤到其他 searchAppearance，则无法按 byNewsShowcasePanel 进行汇总。
  • “byPage”：按 URI 聚合值。
  • “byProperty”：按媒体资源汇总值。不支持 type=discover 或 type=googleNews
rowLimit integer [可选；有效范围为 1-25,000；默认值为 1,000] 要返回的最大行数。如需分页浏览结果，请使用 startRow 偏移量。
startRow integer [可选；默认值为 0] 响应中第一行的索引（从零开始）。必须是非负数。如果 startRow 超过查询的结果数，则响应将是包含零行的成功响应。
dataState string [可选] 如果为“all”（不区分大小写），数据将包含最新数据。 如果值为“final”（不区分大小写），或者省略此参数，则返回的数据将仅包含最终数据。 如果值为“hourly_all”（不区分大小写），数据将包含每小时细分数据。这表示每小时数据包含部分数据，应在按 HOUR API 维度分组时使用。

响应

结果会根据请求中指定的维度进行分组。具有相同维度值集的所有值将分组到一行中。例如，如果您按国家/地区维度进行分组，则“美国”的所有结果将归为一组，“马尔代夫”的所有结果将归为一组，依此类推。如果您按国家/地区和设备进行分组，则“美国、平板电脑”的所有结果将归为一组，“美国、移动设备”的所有结果将归为一组，依此类推。如需详细了解点击次数、展示次数等的计算方式及其含义，请参阅搜索分析报告文档。

除非您按日期进行分组，否则结果会按点击次数降序排序；如果您按日期进行分组，结果会按日期升序排序（从最早到最新）。如果两行之间存在并列情况，则排序顺序是任意的。

请参阅请求中的 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 对实际数据调用此方法，然后查看响应。