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

# Google 검색 결과 API (GOOGLE_SERP)

> AI 개요를 기다리지 않고 검색어 하나에 대한 google.com 자연 검색 결과, 광고, SERP 패널을 한 페이지씩 받습니다.

`GOOGLE_SERP`는 google.com 결과 페이지 하나를 불러와 자연 검색 결과와 패널을 반환합니다. AI 개요를 기다리지 않으므로 [`GOOGLE`](/ko/engines/google-ai-overviews)보다 빠르게 답하고 비용도 적습니다. 순위 추적에 쓰거나, [`WEB_SCRAPE`](/ko/engines/web-scrape)로 읽을 페이지를 찾을 때 쓰세요.

| | |
| - | - |
| `taskType` | `GOOGLE_SERP` |
| 입력 | `query`(필수), `page`, `country`, `location`, `include` |
| 크레딧 | 태스크당 1 |
| 국가 | 기본값 `US`. 모든 ISO 3166-1 alpha-2 코드를 받습니다. |
| 위치 | 지원합니다. [지역과 위치](/ko/engines/capacity.md)를 참고하세요. |

## 요청

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "GOOGLE_SERP", "payload": { "query": "best running shoes for flat feet", "country": "US", "page": 2 } }'
```

태스크는 비동기로 실행됩니다. 결과는 [비동기 태스크](/ko/concepts/async-tasks.md)에 설명한 방법으로 읽으세요.

## 파라미터

| 필드 | 필수 | 설명 |
| - | - | - |
| `query` | 예 | 검색어, 1\~100,000자. `query`가 없으면 `prompt`를 받습니다. |
| `page` | 아니요 | 결과 페이지, 1\~10의 정수. 기본값은 `1`입니다. 페이지마다 자연 검색 결과 10건이 담깁니다. 다른 값은 `422 VALIDATION_ERROR`를 반환합니다. |
| `country` | 아니요 | 검색할 Google 시장. 기본값은 `US`입니다. |
| `location` | 아니요 | 십진 도 단위의 `{ "latitude", "longitude" }`. Google은 그 지점에 있는 사용자에게 답하듯 답하고, 결과의 `location`에 같은 지점을 돌려줍니다. |
| `include.rawResponse` | 아니요 | `true`면 결과 페이지 HTML을 `rawContent`로 더합니다. 페이지가 커서 1MB 가까이 되는 경우가 많습니다. |

## 응답

예를 들어 한 검색어의 2페이지는 다음과 같습니다.

```json theme={"theme":"css-variables"}
{
  "organicResults": [
    { "position": 11, "title": "...", "link": "https://...", "displayedLink": "...", "snippet": "...", "page": 2 }
  ],
  "peopleAlsoAsk": [{ "...": "..." }],
  "relatedSearches": [{ "...": "..." }],
  "ads": [{ "...": "..." }],
  "page": 2
}
```

| 필드 | 설명 |
| - | - |
| `organicResults` | 항상 있습니다. `position`은 페이지를 넘어 이어서 세므로 2페이지 첫 결과는 `11`입니다. 모든 행에 출처 페이지 `page`가 붙습니다. |
| `page` | 불러온 페이지. |
| `peopleAlsoAsk`, `relatedSearches`, `knowledgeGraph` | 페이지에 있을 때 Google의 패널. |
| `ads` | 페이지에 있을 때 상단과 하단 광고. |
| `map` | 페이지에 있을 때 로컬 팩. 장소마다 `name`, `position`, `placeId`, `location`, `mapsUrl`, `reviews` 등이 담깁니다. |
| `serp` | 있을 때 그 밖의 패널: `topStories`, `videoResults`, `localMap`, `discussionsAndForums`. |
| `location` | 보낸 경우 보낸 지점. |
| `rawContent` | `include.rawResponse: true`일 때 결과 페이지 HTML. |

페이지에 없는 패널은 `null`이나 `[]`로 보내지 않고 생략합니다. `organicResults`와 `page`를 제외한 모든 필드를 선택 필드로 다루세요. `aioverview`, `text`, `sources`는 없습니다. AI 개요는 [`GOOGLE`](/ko/engines/google-ai-overviews)을 쓰세요.

## 제한과 오류

* 완료된 태스크의 `organicResults`가 비어 있으면 Google 자체가 그 검색어에 결과를 내지 않았다는 뜻입니다. 반환하기 전에 다른 브라우저에서 한 번 더 확인합니다.
* 1\~10을 벗어난 `page`는 `422 VALIDATION_ERROR`를 반환합니다.
* 형식이 잘못된 `location`은 `400 VALIDATION_ERROR`를 반환합니다.
* 그 밖의 요청 오류는 [오류](/ko/concepts/errors.md)에 정리되어 있습니다.

## 관련 문서

* 같은 페이지를 AI 개요와 함께 받는 [Google AI 개요](/ko/engines/google-ai-overviews.md)
* 결과 페이지를 Markdown으로 읽는 [웹 스크레이프](/ko/engines/web-scrape.md)
* [지역과 위치](/ko/engines/capacity.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.