> ## 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 기본 검색 엔진으로 검색합니다.

**엔드포인트:** `GET /customsearch/v1`

제공한 `cx`로 Google Custom Search를 호출합니다. `cx`를 생략하면 YouRouter 기본 검색 엔진을 사용합니다.

최신 웹 결과 확보, 문서 검색, 자체 사이트에 Programmable Search Engine을 연결하는 경우에 적합합니다.

<Note>
  검색 요청에도 [제로 컴플리션 보험](/ko/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을 구성한 뒤, 검색 결과를 가져와 모델에 넘기면 시의성 있는 제품 Q\&A를 만들 수 있습니다.
  </Accordion>

  <Accordion title="실시간 웹 검색">
    검색으로 최신 기사·웹페이지·공지를 가져온 다음, 모델이 요약·비교·추론을 수행하도록 할 수 있습니다.
  </Accordion>
</AccordionGroup>