> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Search

> 使用你的 Google Custom Search Engine 或 YouRouter 默认搜索引擎进行搜索。

**Endpoint:** `GET /customsearch/v1`

使用你提供的 `cx` 调用 Google Custom Search。如果省略 `cx`，则使用 YouRouter 的默认搜索引擎。

这个接口适合获取新鲜网页结果、文档检索，或者为你自己的站点接入 Programmable Search Engine。

<Note>
  搜索请求也适用 [零完成保险](/zh/features/zero-completion-insurance)。失败或空搜索结果不会按成功 completion 计费。
</Note>

<CodeGroup>
  ```python Python theme={null}
  import os
  import requests
  import json

  response = requests.get(
      "https://api.yourouter.ai/customsearch/v1",
      headers={"Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}"},
      params={
          "q": "how to set up billing",
          "cx": "YOUR_CUSTOM_SEARCH_ENGINE_ID",
          "num": 3
      }
  )
  print(json.dumps(response.json(), indent=2))
  ```

  ```bash cURL theme={null}
  curl "https://api.yourouter.ai/customsearch/v1?q=billing&cx=YOUR_CX_ID" \
    -H "Authorization: Bearer $YOUROUTER_API_KEY"
  ```
</CodeGroup>

### 参数

| 参数           | 类型      | 说明                                              | 必填 |
| ------------ | ------- | ----------------------------------------------- | -- |
| `q`          | string  | 搜索关键词。                                          | 是  |
| `cx`         | string  | Custom Search Engine ID。省略时使用 YouRouter 默认搜索引擎。 | 否  |
| `num`        | integer | 返回结果数量，范围 1 到 10。                               | 否  |
| `start`      | integer | 返回结果的起始索引。                                      | 否  |
| `siteSearch` | string  | 限定在特定站点内搜索。                                     | 否  |

<Card title="响应格式" icon="code">
  成功响应中会包含一个 `items` 数组，数组中的每个元素都是一条搜索结果对象。

  ```json theme={null}
  {
    "kind": "customsearch#search",
    "items": [
      {
        "kind": "customsearch#result",
        "title": "Billing Information - Example Docs",
        "link": "https://docs.example-app.ai/billing"
      }
    ]
  }
  ```
</Card>

## 典型使用场景

<AccordionGroup>
  <Accordion title="对自家文档做问答">
    你可以为自己的文档域名配置一个 Google Programmable Search Engine，然后先把搜索结果取回来，再交给模型生成更具时效性的产品问答结果。
  </Accordion>

  <Accordion title="实时网页检索">
    先用搜索结果获取最新文章、网页或公告，再让模型做摘要、比较或推理。
  </Accordion>
</AccordionGroup>