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”。系统会合并这些分组维度值，为每个结果行创建一个唯一键。如果未指定维度，则所有值都将合并为一行。可以作为分组依据的维度数量没有限制，但是您不能按相同的维度分组两次。示例：[country, device]
searchType string 已弃用，请改用 type
type string [可选] 将结果过滤为以下类型： <ph type="x-smartling-placeholder">
    </ph>
  • “discover”：Google 探索结果
  • “googleNews”：来自 news.google.com 和 Google 新闻应用的搜索结果 Android 和 iOS。不包含来自“新闻”的搜索结果标签页。
  • “news”：来自“Google 新闻”的搜索结果标签页。
  • “image”：来自“图片”的搜索结果标签页。
  • “video”：视频搜索结果
  • “web”：[默认] 将结果过滤到以下位置中的组合（“全部”）标签页： Google 搜索。不包括 Google 探索或 Google 新闻结果。
dimensionFilterGroups[] list [可选] 可应用于维度分组值的零组或多组过滤条件。所有过滤条件组必须匹配，系统才会在响应中返回一行。在单个过滤条件组中，您可以指定是必须匹配所有过滤条件，还是必须至少匹配一个过滤条件。
dimensionFilterGroups[].groupType string 是此群组中的所有过滤条件必须返回 true（“and”），还是一个或多个过滤条件必须返回 true（尚不支持）。

可接受的值包括： <ph type="x-smartling-placeholder">
    </ph>
  • “and”：对于过滤条件组，组中的所有过滤条件都必须返回 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 [可选] 指定的值必须与行的维度值匹配（或不匹配）。

可接受的值包括： <ph type="x-smartling-placeholder">
    </ph>
  • “contains”：行值必须包含或等于表达式（不区分大小写）。
  • “equals”：[默认] 表达式必须与行值完全一致（对于网页维度和查询维度，区分大小写）。
  • “notContains”：行值不得包含表达式，无论是子字符串还是（不区分大小写）完全匹配。
  • “notEquals”：您的表达式不得与行值完全一致（对于网页维度和查询维度，区分大小写）。
  • “includingRegex”： RE2 语法必须匹配的正则表达式。
  • “excludingRegex”： RE2 语法正则表达式。
dimensionFilterGroups[].filters[].expression string 要匹配或排除的过滤条件的值（具体取决于运算符）。
aggregationType string

[可选] 如何汇总数据。如果按媒体资源汇总， 汇总相同的媒体资源；如果按网页汇总，所有数据都会按规范网址汇总 URI如果您要按网页进行过滤或分组，请选择“自动”；否则，您可以按 媒体资源或网页，具体取决于您所需的数据计算方式；请参阅 帮助文档 了解按网站和网页计算数据的不同之处。

注意： 如果您按网页进行分组或过滤，则无法按资源汇总。

如果您指定任何 值（非 auto），那么结果中的汇总类型将与所请求的类型匹配，或者 如果您请求的类型无效，则会收到错误消息。如果请求的汇总类型无效，API 绝不会更改您的汇总类型。

可接受的值包括： <ph type="x-smartling-placeholder">
    </ph>
  • "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”（不区分大小写），或者省略此参数，那么返回的数据将只包含最终数据。

响应

根据请求中指定的维度对结果进行分组。包含同一组维度值的所有值都会归为一行。例如，如果您按“国家/地区”维度进行分组，则搜索“usa”的所有结果会归为一组，所有与“mdv”相符的结果会归为一组，依此类推。如果您按国家/地区和设备进行分组，则搜索“美国、平板电脑”的所有结果会分组，所有“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 如何汇总结果。请参阅帮助文档，了解按网站和网页计算数据的不同之处。

可接受的值包括： <ph type="x-smartling-placeholder">
    </ph>
  • “auto”
  • “byPage”：结果按网页汇总。
  • “byProperty”：结果按资源汇总。

试试看！

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