> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-scraper-api/mu-biao/sou-suo-yin-qing/gu-ge/ai-overviews.md).

# AI Overviews

从搜索结果中提取 Google AI Overviews，获取答案文本、项目符号列表、来源面板和信息列表的解析数据。

该 `google_search` 来源和 `google_ads` 来源可以在所有受支持的全球地区从 Google Search 结果中返回 AI Overviews。 `ai_overviews` 结果数组支持在单个响应中包含多个 AI 块，包括“People also ask”和“Things to know.”等部分。

为了尽可能获取完整渲染的 AI Overviews 内容，你必须包含以下参数：

| 参数                | 值                              |
| ----------------- | ------------------------------ |
| `source`          | `google_search` 或 `google_ads` |
| `render`          | `html`                         |
| `user_agent_type` | `桌面端` 或 `移动端`                  |

使用这些参数还可以让你通过单个请求同时获取通用响应和 AI Overviews 内容。

{% hint style="danger" %}
Google 会动态生成此内容或加载缓存版本，因此即使参数相同，AI 生成的答案也可能随时间变化。
{% endhint %}

{% hint style="success" %}
探索[ **数据字典**](#data-dictionary) 部分 AI Overviews SERP 功能。
{% endhint %}

## AI Overviews 区域可用性

Google AI Overviews 可在大多数国家/地区使用，但有少数例外。目前排除最多的国家/地区是：

* 法国
* 摩纳哥
* 中国
* 伊朗
* 苏丹
* 叙利亚
* 古巴
* 朝鲜

{% hint style="warning" %}
Google AI Overviews 功能正在持续推广，随着时间推移会纳入更多国家/地区。
{% endhint %}

## 请求示例

以下是使用 `google_search` 网页爬虫API 来源以抓取 Google AI Overviews。

{% tabs %}
{% tab title="cURL" %}

```shell
curl 'https://data.oxylabs.io/v1/queries' \
--user 'USERNAME:PASSWORD' \
-H 'Content-Type: application/json' \
-d '{
        "source": "google_search",
        "query": "how to sell on amazon",
        "render": "html",
        "user_agent_type": "desktop",
        "parse": true
        
    }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
from pprint import pprint

# Updated payload.
payload = {
    'source': 'google_search',
    'query': 'how to sell on amazon',
    'render': 'html',
    'user_agent_type': 'desktop',
    'parse': True,
}

# Get response.
response = requests.request(
    'POST',
    'https://data.oxylabs.io/v1/queries',
    auth=('user', 'pass1'),
    json=payload,
)

# 将格式化后的响应打印到标准输出。
pprint(response.json())
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$params = [
    'source' => 'google_search',
    'query' => 'how to sell on amazon',
    'render' => 'html',
    'user_agent_type' => 'desktop',
    'parse' => true,
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://data.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "user" . ":" . "pass1");

$headers = [];
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
```

{% endtab %}

{% tab title="JSON" %}

```json
{
    "source": "google_search",
    "query": "how to sell on amazon",
    "render": "html",
    "user_agent_type": "desktop",
    "parse": true
}
```

{% endtab %}
{% endtabs %}

我们使用 [**Push-Pull**](https://developers.oxylabs.io/products/cn/web-scraper-api/integration-methods/push-pull.md) 集成方式在示例中。提交任务后会立即返回任务 ID，而不是结果。一旦任务状态为 `完成`，请使用以下方式获取结果： `GET https://data.oxylabs.io/v1/queries/{job_id}/results`。请参阅 [**Push-Pull**](https://developers.oxylabs.io/products/cn/web-scraper-api/integration-methods/push-pull.md) 以了解如何检查任务状态、回调和批量查询。

### 处理多个 AI Overviews

由于 AI Overviews 现在以数组返回，你必须遍历它们：

{% tabs %}
{% tab title="JavaScript" %}

```javascript
// Processing all AI Overviews in a response
response.results[0].content.results.ai_overviews.forEach((aiOverview, index) => {
  console.log(`Processing AI Overview #${index + 1}`);
  // Process individual components
  if (aiOverview.answer_text) {
    // Handle answer text
  }
  if (aiOverview.bullet_list) {
    // Handle bullet lists
  }
  // And so on...
});
```

{% endtab %}

{% tab title="Python" %}

```python
# Processing all AI Overviews in a response
for index, ai_overview in enumerate(response['results'][0]['content']['results']['ai_overviews']):
    print(f"Processing AI Overview #{index + 1}")
    # Process individual components
    if 'answer_text' in ai_overview:
        answer_texts = ai_overview['answer_text']
        for answer in answer_texts:
            # Process each answer text
            if 'fragments' in answer:
                for fragment in answer['fragments']:
                    print(f"Answer text: {fragment['text']}")
    
    if 'bullet_list' in ai_overview:
        bullet_lists = ai_overview['bullet_list']
        for bullet_list in bullet_lists:
            if 'list_title' in bullet_list:
                print(f"List title: {bullet_list['list_title']}")
            if 'points' in bullet_list:
                for point in bullet_list['points']:
                    point_text = point['text']
                    print(f"- {point_text}")
    # Continue processing other elements...
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
// Processing all AI Overviews in a response
if (isset($response['results'][0]['content']['results']['ai_overviews']) && is_array($response['results'][0]['content']['results']['ai_overviews'])) {
    foreach ($response['results'][0]['content']['results']['ai_overviews'] as $index => $aiOverview) {
        $indexNumber = $index + 1;
        echo "Processing AI Overview #{$indexNumber}\n";
        
        // Process answer text
        if (isset($aiOverview['answer_text']) && is_array($aiOverview['answer_text'])) {
            foreach ($aiOverview['answer_text'] as $answer) {
                if (isset($answer['fragments']) && is_array($answer['fragments'])) {
                    foreach ($answer['fragments'] as $fragment) {
                        $textItem = $fragment['text'];
                        echo "Answer text: {$textItem}\n";
                    }
                }
            }
        }
        
        // Process bullet lists
        if (isset($aiOverview['bullet_list']) && is_array($aiOverview['bullet_list'])) {
            foreach ($aiOverview['bullet_list'] as $bulletList) {
                if (isset($bulletList['list_title'])) {
                    echo "List title: {$bulletList['list_title']}\n";
                }
                if (isset($bulletList['points']) && is_array($bulletList['points'])) {
                    foreach ($bulletList['points'] as $point) {
                        $pointText = $point['text'];
                        echo "- {$pointText}\n";
                    }
                }
            }
        }
        // Continue processing other elements...
    }
}
?>
```

{% endtab %}
{% endtabs %}

在大多数情况下，只会有一个 AI Overview，但你的代码应准备好处理多个条目。

## 请求参数

### 通用

使用 AI Overviews 抓取 Google 网页搜索结果的基本设置和自定义选项。

<table><thead><tr><th width="191">参数</th><th width="377.3333333333333">说明</th><th>默认值</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><strong>source</strong></mark></td><td>设置抓取器。使用 <code>google_search</code> 或 <code>google_ads</code>.</td><td><code>google_search</code></td></tr><tr><td><mark style="background-color:green;"><strong>query</strong></mark></td><td>要搜索的关键词或短语。</td><td>-</td></tr><tr><td><code>render</code></td><td>设置为时启用 JavaScript 渲染 <code>html</code>. <a href="https://developers.oxylabs.io/products/cn/web-scraper-api/features/js-rendering-and-browser-control.md#javascript-rendering"><strong>更多信息</strong></a><strong>.</strong></td><td>-</td></tr><tr><td><code>context</code>:<br><code>expand_aio</code></td><td>设为 <code>true</code> 用于展开 Google AI Overviews（已启用 JavaScript 渲染）。</td><td><code>false</code></td></tr><tr><td><code>parse</code></td><td>设置为时返回解析后的数据 <code>true</code>.</td><td><code>false</code></td></tr><tr><td><code>callback_url</code></td><td>回调端点的 URL。 <a href="https://developers.oxylabs.io/products/cn/web-scraper-api/integration-methods/push-pull.md"><strong>更多信息</strong></a></td><td>-</td></tr><tr><td><code>user_agent_type</code></td><td>设备类型和浏览器。使用 <code>桌面端</code> 或 <code>移动端</code>.</td><td><code>桌面端</code></td></tr></tbody></table>

\- 必填参数

#### Google 高级搜索运算符

在抓取时，将 Google 高级搜索运算符与你的查询结合使用可能很有帮助。它可以让你自定义搜索范围，确保结果更相关、更聚焦。了解这些特殊命令 [**这里**](https://ahrefs.com/blog/google-advanced-search-operators/)。请参见下面的示例查询。

```json
{
    "source": "google_search",
    "query": "iphone 15 launch inurl:apple", 
    "render": "html",
    "user_agent_type": "desktop"
}
```

### 本地化

将搜索结果适配到特定地理位置和语言。

<table><thead><tr><th width="222">参数</th><th width="350.3333333333333">说明</th><th>默认值</th></tr></thead><tbody><tr><td><code>geo_location</code></td><td>结果应适配的地理位置。正确使用此参数对于获取正确数据极其重要。更多信息请参阅我们推荐的 <code>geo_location</code> 参数结构 <a href="https://developers.oxylabs.io/products/cn/web-scraper-api/features/localization/serp-localization.md#google"><strong>这里</strong></a><strong>.</strong></td><td>-</td></tr><tr><td><code>locale</code></td><td><code>Accept-Language</code> 标头值，可更改你的 Google 搜索页面网页界面语言。 <a href="https://developers.oxylabs.io/products/cn/web-scraper-api/features/localization/domain-locale.md#google"><strong>更多信息</strong></a>.</td><td>-</td></tr></tbody></table>

### 分页

用于管理分页和检索搜索结果的控制项。

<table><thead><tr><th width="222">参数</th><th width="350.3333333333333">说明</th><th width="167">默认值</th></tr></thead><tbody><tr><td><code>start_page</code></td><td>起始页码。</td><td><code>1</code></td></tr><tr><td><code>pages</code></td><td>要检索的页数。</td><td><code>1</code></td></tr><tr><td><code>limit</code></td><td>每页要检索的结果数量。</td><td><code>10</code></td></tr><tr><td><code>context</code>:<code>limit_per_page</code></td><td>使用相同的 IP 地址和会话（Cookie 集）抓取多个页面。通过在 JSON 数组中使用 <code>page</code> 键指定页面编号，并使用 <code>limit</code> 键指示每页自然结果的数量，你可以尽量减少跨页面出现重叠自然结果的可能性（例如第一页的最后一个自然结果与第二页的第一个自然结果相同）。 <a href="#request-sample"><strong>查看示例</strong></a><strong>.</strong></td><td>-</td></tr></tbody></table>

#### 支持连续滚动

网页爬虫API 完全支持 Google Search 连续滚动。它会自动检测连续滚动布局，在无需任何额外参数的情况下高效加载所请求的自然结果。

#### 每页限制

{% hint style="warning" %}
由于 Google 最近的限制变更，我们已调整网页爬虫API 的行为。每页的最大结果数将与 Google 的自然结果输出一致，通常为 10 个结果。
{% endhint %}

要使用此功能，请包含一个 JSON 数组，其中的 JSON 对象包含以下数据：

<table><thead><tr><th width="142">参数</th><th width="446.3333333333333">说明</th><th>示例</th></tr></thead><tbody><tr><td><code>page</code></td><td>你要抓取的页面编号。任何大于 <code>0</code> 的整数都可以</td><td><code>1</code></td></tr><tr><td><code>limit</code></td><td>相关页面上的结果数量。任何介于 <code>1</code> 和 <code>100</code> （含）之间的整数都可以。</td><td><code>90</code></td></tr></tbody></table>

#### 请求示例

```json
{
    "source": "google_search",
    "query": "how to sell on amazon",
    "render": "html",
    "user_agent_type": "desktop",
    "parse": true,
    "context": [
        {
            "key": "limit_per_page",
            "value": [
                {"page": 1, "limit": 10},
                {"page": 2, "limit": 90}
                    ]
        }]
}
```

### 过滤

根据各种条件过滤和优化搜索结果的选项。了解如何使用 context 参数 [**这里**](#context-parameters).

<table><thead><tr><th width="245">参数</th><th width="350.3333333333333">说明</th><th>默认值</th></tr></thead><tbody><tr><td><code>context</code>:<br><code>filter</code></td><td>将此参数的值设置为 <code>0</code> 可以让你看到原本会因与其他结果相似而被排除的结果。</td><td><code>1</code></td></tr><tr><td><code>context</code>:<br><code>safe_search</code></td><td>安全搜索。设置为 <code>true</code> 即可启用。</td><td><code>false</code></td></tr><tr><td><code>context</code>:<br><code>udm</code></td><td><code>udm</code> 参数可在不同搜索标签之间切换，例如图片、地点或视频，以自定义显示的结果类型。查看可接受的值 <a href="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FeoShpvYuZlb4hGpCIXNG%2Fudm_values%20(eu%2Bus).json?alt=media&#x26;token=a6b77fab-b170-478c-b06f-b8fbf7ab64c7"><strong>这里</strong></a>.</td><td>-</td></tr><tr><td><code>context</code>:<br><code>tbm</code></td><td>待匹配或 <code>tbm</code> 参数。可接受的值为： <code>app</code>, <code>blg</code>, <code>bks</code>, <code>dsc</code>, <code>isch</code>, <code>nws</code>, <code>pts</code>, <code>plcs</code>, <code>rcp</code>, <code>lcl</code></td><td>-</td></tr><tr><td><code>context</code>:<br><code>tbs</code></td><td>此参数类似于一个容器，用于承载更隐蔽的 Google 参数，例如按日期限制/排序结果以及其他过滤条件，其中一些取决于 <code>tbm</code> 参数（例如 <code>tbs=app_os:1</code> 仅可与 <code>tbm</code> value <code>app</code>)。更多信息 <a href="https://stenevang.wordpress.com/2013/02/22/google-advanced-power-search-url-request-parameters/"><strong>这里</strong></a>.</td><td>-</td></tr></tbody></table>

{% hint style="warning" %}
`udm` 和 `tbm` context 参数不能在单次抓取请求中同时使用；请只选择一个。同时使用两者可能导致冲突或意外行为。
{% endhint %}

### 其他

用于特殊需求的附加高级设置和控制项。

<table><thead><tr><th width="222">参数</th><th width="350.3333333333333">说明</th><th>默认值</th></tr></thead><tbody><tr><td><code>context</code>:<br><code>fpstate</code></td><td>将 <code>fpstate</code> 值设置为 <code>aig</code> 会让 Google 加载更多应用。此参数仅在与 <code>render</code> 参数一起使用时才有用。</td><td>-</td></tr><tr><td><code>context</code>:<br><code>nfpr</code></td><td><code>true</code> 将关闭拼写自动更正</td><td><code>false</code></td></tr></tbody></table>

### 上下文参数

所有上下文参数都应添加到 `context` 数组中，作为包含 `key` 和 `value` 对，例如：

```json
...
"context": [
    {
        "key": "filter",
        "value": "0"
    }
]
...
```

## 结构化输出

### 数据字典

下表定义了 AI Overviews SERP 功能中的所有可用键：

<table><thead><tr><th width="249">键 (results.ai_overviews)</th><th width="383">说明</th><th>类型</th></tr></thead><tbody><tr><td><code>answer_text</code></td><td>关于 Google Search 查询词的一般信息。</td><td>数组</td></tr><tr><td><code>bullet_list</code></td><td>表示 AI Overviews SERP 功能中以项目符号列表呈现的项目信息。</td><td>数组</td></tr><tr><td><code>source_panel</code></td><td>用于生成 Google SERP 功能中 AI Overviews 结果的来源列表。</td><td>对象</td></tr><tr><td><code>info_list</code></td><td>最常用于表示与搜索查询相关流程步骤的信息列表。</td><td>数组</td></tr><tr><td><code>pos_overall</code></td><td>表示 AI Overviews SERP 功能结果在所有可用 Google SERP 结果中的位置。</td><td>整数</td></tr></tbody></table>

### 通用

在下面的示例中，使用了“Emporio Armani EA3192”查询。

```json
{
  "ai_overviews": [
    {
      "answer_text": [
        {
          "fragments": [
            {
              "text": "Emporio Armani is a luxury brand known for timeless designs.",
              "references": [
                {
                  "source": "http://italist.com ",
                  "url": "https://www.italist.com/magazine/what-is-emporio-armani/ "
                }
              ]
            }
          ],
          "pos": 1
        }
      ],
      "bullet_list": [
        {
          "list_title": "Pros",
          "points": [
            {"text": "Comfortable"},
            {"text": "Minimal branding"}
          ],
          "pos": 1
        }
      ],
      "source_panel": {
        "items": [
          {
            "url": "https://www.italist.com/...",
            "source": "http://italist.com ",
            "title": "What is Emporio Armani...",
            "pos": 1
          }
        ]
      },
      "pos_overall": 1
    }
  ]
}
```

#### 答案文本

<pre class="language-json"><code class="lang-json"><strong>...
</strong><strong>"answer_text": [
</strong>  {
    "fragments": [
      {
        "text": "Emporio Armani is a luxury brand known for timeless designs.",
        "references": [
          {
            "source": "http://italist.com",
            "url": "https://www.italist.com/magazine/what-is-emporio-armani/"
          }
        ]
      }
    ],
    "pos": 1
  }
]
...
</code></pre>

<table><thead><tr><th width="273">键 (results.ai_overviews.answer_text)</th><th width="368">说明</th><th>类型</th></tr></thead><tbody><tr><td><code>fragments</code></td><td>对 Google Search 查询的简短回答。</td><td>数组</td></tr><tr><td><code>fragments.text</code></td><td>片段的答案文本内容。</td><td>字符串</td></tr><tr><td><code>fragments.references</code></td><td>片段引用的来源列表。</td><td>数组</td></tr><tr><td><code>fragments.references.source</code></td><td>被引用来源的名称。</td><td>字符串</td></tr><tr><td><code>fragments.references.url</code></td><td>被引用来源的 URL。</td><td>字符串</td></tr><tr><td><code>pos</code></td><td>表示某个项目在所有 AI Overviews 答案结果中的位置。</td><td>整数</td></tr></tbody></table>

#### **项目符号列表**

```json
...
"bullet_list": [
  {
    "list_title": "Pros",
    "points": [
      {"text": "Comfortable"},
      {"text": "Minimal branding"}
    ],
    "pos": 1
  }
]
...
```

<table><thead><tr><th width="268">键 (results.ai_overviews.bullet_list)</th><th width="364">说明</th><th>类型</th></tr></thead><tbody><tr><td><code>list_title</code></td><td>项目符号列表的标题。</td><td>字符串</td></tr><tr><td><code>points</code></td><td>在项目符号列表中呈现的项目。所有项目以逗号分隔。</td><td>数组</td></tr><tr><td><code>points.text</code></td><td>项目符号项的文本内容。</td><td>字符串</td></tr><tr><td><code>points.references</code></td><td>项目符号项引用的来源列表（可选）。</td><td>数组</td></tr><tr><td><code>pos</code></td><td>表示某个项目在所有 AI Overviews 项目符号列表结果中的位置。</td><td>整数</td></tr></tbody></table>

#### 来源面板

```json
...
"source_panel": {
  "items": [
    {
      "url": "https://www.italist.com/...",
      "source": "http://italist.com",
      "title": "What is Emporio Armani...",
      "pos": 1
    }
  ]
}
...
```

<table><thead><tr><th width="274">键 (results.ai_overviews.source_panel)</th><th width="353">说明</th><th>类型</th></tr></thead><tbody><tr><td><code>items</code></td><td>用于生成 Google SERP 功能中 AI Overviews 结果的来源列表。</td><td>对象</td></tr><tr><td><code>items.url</code></td><td>网站的 URL。</td><td>字符串</td></tr><tr><td><code>items.source</code></td><td>网站名称。</td><td>字符串</td></tr><tr><td><code>items.title</code></td><td>文章标题。</td><td>字符串</td></tr><tr><td><code>items.pos</code></td><td>表示某个项目在所有 AI Overviews 来源面板结果中的位置。</td><td>整数</td></tr></tbody></table>

#### 信息列表

<table><thead><tr><th width="276">键 (results.ai_overviews.info_list)</th><th width="353">说明</th><th>类型</th></tr></thead><tbody><tr><td><code>list_title</code></td><td>列表标题。</td><td>字符串</td></tr><tr><td><code>list_items</code></td><td>包含一组项目及其各自的详细信息。</td><td>数组</td></tr><tr><td><code>list_items.title</code></td><td>列表中该部分的标题。</td><td>字符串</td></tr><tr><td><code>list_items.content</code></td><td>该部分的简短描述。</td><td>数组</td></tr><tr><td><code>list_item.pos</code></td><td>表示某个项目在所有 AI Overviews 信息列表结果中的位置。</td><td>整数</td></tr></tbody></table>

### 说明

在下面的示例中，使用了“docker exec commands explained”查询。

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-648a33922f3380889e3086bf204735af9703ff25%2Fdocker_exec_command_explained.png?alt=media" alt=""><figcaption></figcaption></figure>

```json
...
  "ai_overviews": [
    {
      "answer_text": [
        {
          "fragments": [
            "The docker execExecIn computing, exec is a functionality of an operating system that runs an executable file in the context of an already existing process, replacing the previous executable...",
            "It is a powerful tool that can be used for a variety of tasks, such as troubleshooting a container, running a script, or installing software."
          ],
          "pos": 1
        },
        {
          "fragments": [
            "The syntax for the docker exec command is as follows:"
          ],
          "pos": 2
        },
        ...
        }
      ]
    }
  ],
...
```

#### 答案文本

```json
"answer_text": [
  {
    "fragments": [
      "The docker exec...",
      "It is a powerful tool that can be used for a variety of tasks, such as troubleshooting a container, running a script, or installing software."
    ],
    "pos": 1
  }
]
```

<table><thead><tr><th width="260">键 (results.ai_overviews.answer_text)</th><th width="385">说明</th><th width="89">类型</th></tr></thead><tbody><tr><td><code>fragments</code></td><td>以纯文本形式表示的 Google Search 查询答案片段。</td><td>字符串数组</td></tr><tr><td><code>pos</code></td><td>表示该项在概览答案中的位置。</td><td>整数</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-scraper-api/mu-biao/sou-suo-yin-qing/gu-ge/ai-overviews.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
