> ## 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.

# 네이버 검색 결과 API (NAVER_SERP)

> 검색어 하나에 대한 네이버 웹문서 결과를 한 페이지씩 받거나, naver.com 페이지 하나를 텍스트로 읽습니다.

`NAVER_SERP`는 네이버 웹문서 탭 결과 한 페이지(페이지당 15건)를 반환합니다. `"action": "page"`를 보내면 naver.com 페이지 하나(블로그 글, 카페 글, 뉴스 기사, 지식iN 답변 등 모든 naver.com 페이지)를 읽어 그 텍스트를 반환합니다.

| | |
| - | - |
| `taskType` | `NAVER_SERP` |
| 입력 | 검색: `query`(필수), `page`, `country` / 페이지 읽기: `action: "page"`와 `url`, `maxChars` |
| 크레딧 | 태스크당 1 |
| 국가 | 기본값 `KR`. |
| 위치 | 지원하지 않습니다(`422 LOCATION_UNSUPPORTED`). |

## 검색

```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": "NAVER_SERP", "payload": { "query": "running shoes for flat feet", "page": 2 } }'
```

| 필드 | 필수 | 설명 |
| - | - | - |
| `query` | 예 | 검색어, 1\~100,000자. `query`가 없으면 `prompt`를 받습니다. |
| `page` | 아니요 | 결과 페이지, 1\~10의 정수. 기본값은 `1`입니다. 다른 값은 `422 VALIDATION_ERROR`를 반환합니다. |
| `country` | 아니요 | 기본값은 네이버의 시장인 `KR`입니다. |

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

```json theme={"theme":"css-variables"}
{
  "organicResults": [
    { "position": 16, "title": "...", "link": "https://...", "displayedLink": "example.com›path", "snippet": "...", "page": 2 }
  ]
}
```

| 필드 | 설명 |
| - | - |
| `organicResults` | 페이지의 문서. `position`은 페이지를 넘어 이어서 세므로 2페이지 첫 문서는 `16`입니다. 모든 행에 `page`가 붙습니다. |
| `notice` | 네이버가 연령 확인 뒤로 결과를 숨겼을 때 붙습니다: `{ "type": "age_verification_required", "scope": "organicResults", "message" }`. `message`는 읽을 수 있으면 네이버의 문구를 그대로 담습니다. |

완료된 태스크의 `organicResults`가 비어 있으면 네이버 자체가 문서를 돌려주지 않았다는 뜻입니다.

## naver.com 페이지 읽기

```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": "NAVER_SERP", "payload": { "action": "page", "url": "https://blog.naver.com/example/223000000000", "maxChars": 10000 } }'
```

| 필드 | 필수 | 설명 |
| - | - | - |
| `action` | 예 | `page`. |
| `url` | 예 | `naver.com` 또는 그 하위 도메인의 `https` 주소. 다른 주소는 `422 VALIDATION_ERROR`를 반환합니다. |
| `maxChars` | 아니요 | `text` 길이 상한, 1,000\~50,000의 정수. 기본값은 20,000입니다. |

예:

```json theme={"theme":"css-variables"}
{
  "type": "blog",
  "url": "https://blog.naver.com/example/223000000000",
  "title": "...",
  "text": "...",
  "author": "...",
  "publishedAt": "...",
  "images": ["https://..."],
  "truncated": false
}
```

| 필드 | 설명 |
| - | - |
| `type` | `blog`, `cafe`, `news`, `terms`, `kin`, `generic` 중 하나. |
| `title`, `text` | 페이지의 제목과 본문 텍스트. |
| `author`, `publishedAt`, `cafeName` | 페이지에 있을 때 붙습니다. |
| `images` | 본문의 이미지 주소, 최대 30개. |
| `truncated` | `text`가 `maxChars`에서 잘렸으면 `true`. |

다음 경우에는 태스크가 `PAGE_UNAVAILABLE`과 이유를 담아 실패합니다: naver.com을 벗어나는 리다이렉트, 없는 페이지(404 또는 410), 회원만 읽을 수 있는 카페 글, 읽을 본문이 없는 페이지.

## 제한과 오류

* `NAVER_SERP`는 `markdown`, `rawResponse`, `searchQueries`를 무시합니다. `html`과 `analysis`는 `422`로, `citationAnalysis`는 `400`으로 거절합니다. [지원하지 않는 플래그](/ko/engines/response-options.md#지원하지-않는-플래그)를 참고하세요.
* 그 밖의 요청 오류는 [오류](/ko/concepts/errors.md)에 정리되어 있습니다.

## 관련 문서

* 요약 아래의 웹문서 결과도 반환하는 [네이버 AI 브리핑](/ko/engines/naver-ai-brief.md)
* [네이버 AI 탭](/ko/engines/naver-ai-tab.md)
* [지역과 위치](/ko/engines/capacity.md)


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