---
title: "SERP API"
description: "Google, Bing, Naver, Baidu, Yandex 등 검색 엔진 16개와 지도, 앱 스토어, Google Trends를 공통 오퍼레이션과 스키마 하나로 제공합니다."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/serp/llms.txt)

SERP API는 검색 엔진을 사람이 보는 그대로 읽습니다. 결과 페이지는 화면에 나온 순서대로 돌아옵니다. 일반 검색 결과, 광고,
뉴스, 이미지, 동영상, "다른 사람들이 함께 찾은 질문", 지식 패널, 지역 정보, AI 개요가 모두 포함됩니다. 스키마가 하나라서
Google을 읽는 코드로 Naver도 그대로 읽습니다.

```bash
curl "https://gateway.apinoa.com/v1/google/search?q=best+running+shoes&country=US" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/naver/places?q=강남역+카페" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/google-trends/explore?terms=chatgpt,gemini&country=US" -H "x-api-key: $APINOA_API_KEY"
```

## 오퍼레이션

| 오퍼레이션 | 반환 | 읽는 것 |
|---|---|---|
| `search` | `ResultsPage` | 결과 페이지 하나. `type`으로 웹(기본값), `news`, `images`, `videos`를 고릅니다. 일부 엔진은 `type=image`와 `image` URL로 이미지 검색도 합니다 |
| `suggestions` | `Suggestions` | `q`에 대해 검색창이 제안하는 추천 검색어 |
| `places` | `PlacesPage` | `q`로 찾은 지도 위 장소. 장소 이름은 `near`, 좌표는 `location`(`lat,lng`) 주변 |
| `place` | `Place` | 장소 하나. `places`가 준 `id`나 지도 링크(`url`) |
| `reviews` | `PlaceReviewsPage` | 장소의 리뷰. `place` |

앱 스토어와 Google Trends도 같은 이름을 씁니다. 앱은 `search`, `app`, `reviews`이고, Trends는 `explore`와 `trending`입니다.

## 엔진별 지원 범위

| | search | suggestions | places | place | reviews | 시장 |
|---|:-:|:-:|:-:|:-:|:-:|---|
| [Google](/docs/api-reference/google) | ✓ | ✓ | ✓ | ✓ | | 10 |
| [Bing](/docs/api-reference/bing) | ✓ | ✓ | | | | 10 |
| [Yahoo](/docs/api-reference/yahoo) | ✓ | ✓ | | | | 13 |
| [DuckDuckGo](/docs/api-reference/duckduckgo) | ✓ | ✓ | | | | 14 |
| [Yandex](/docs/api-reference/yandex) | ✓ | ✓ | ✓ | ✓ | ✓ | 10 |
| [Naver](/docs/api-reference/naver) | ✓ | ✓ | ✓ | ✓ | ✓ | KR |
| [Daum](/docs/api-reference/daum) | ✓ | ✓ | | | | KR |
| [Baidu](/docs/api-reference/baidu) | ✓ | ✓ | | | | CN |
| [Sogou](/docs/api-reference/sogou) | ✓ | ✓ | | | | CN |
| [Yahoo! JAPAN](/docs/api-reference/yahoo-japan) | ✓ | ✓ | | | | JP |
| [Seznam](/docs/api-reference/seznam) | ✓ | ✓ | | | | CZ |
| [Tripadvisor](/docs/api-reference/tripadvisor) | | | ✓ | ✓ | ✓ | 15 |

| | 오퍼레이션 |
|---|---|
| [Google Shopping](/docs/api-reference/google-shopping) | `search` `product` `reviews`. 마켓플레이스 타입으로 돌려줍니다 |
| [Google Play](/docs/api-reference/google-play) · [App Store](/docs/api-reference/app-store) | `search` `app` `reviews` |
| [Google Trends](/docs/api-reference/google-trends) | `explore` `trending` |

엔진별 페이지에 오퍼레이션마다 받는 입력이 정리되어 있습니다.

## 입력

이름 하나는 모든 엔진에서 같은 뜻입니다.

| 입력 | 뜻 |
|---|---|
| `q` | 검색어. 검색 연산자도 그대로 씁니다 |
| `type` | 검색할 대상: `web`, `news`, `images`, `videos` (엔진마다 받는 값이 다릅니다) |
| `country` | 시장. ISO 3166 국가 코드 |
| `lang` | 인터페이스 언어 (`en`, `pt-BR`) |
| `device` | `desktop` 페이지(기본값)나 `mobile` 페이지 |
| `timeRange` | 지난 `hour`, `day`, `week`, `month`, `year` 동안의 결과만 |
| `safe` | 세이프서치, `on` 또는 `off` |
| `near` · `location` | `places`용. 장소 이름이나 `lat,lng` 좌표 |
| `id` · `place` | 읽을 장소(또는 앱). `id` 대신 링크를 `url`로 넘길 수도 있습니다 |
| `sort` | 리뷰 순서 |
| `limit` | 원하는 결과 수. 한 페이지를 넘으면 페이지마다 과금합니다 |
| `cursor` | 다음 페이지 |

엔진이 받지 않는 입력은 무시하지 않고 `400 INVALID_PARAMS`로 거절합니다. 요청한 대로 처리하지 않은 페이지에는 과금하지 않습니다.

## 어디서나 같은 것

- **형태.** 모든 오퍼레이션은 [Response Schema](/docs/api-reference/serp/response-schema)에 있는 타입 중 하나를 돌려줍니다.
  한 엔진에만 있는 정보는 `ext`에 들어갑니다.
- **버리는 것이 없습니다.** 페이지의 모든 블록을 페이지 순서대로 `rank`와 함께 돌려줍니다. 아직 공통 형태가 없는 블록은
  `type: "other"`로 옵니다.
- **페이지 넘기기.** 목록은 불투명한 `cursor`를 돌려줍니다. 다음 페이지는 같은 오퍼레이션을 `cursor`만 넣어 호출합니다.
  `cursor`가 없으면 다음 페이지가 없습니다.
- **없음은 0이 아닙니다.** 페이지가 보여 주지 않은 개수나 평점은 `0`으로 채우지 않고 뺍니다. 시각은 ISO 8601, UTC입니다.
- **결과 없음도 응답입니다.** `outcome: "noResults"`는 엔진이 결과가 없다고 말한 경우입니다. 읽지 못한 페이지는 에러이며,
  에러는 과금하지 않습니다.
- **가격.** 단위당 $0.0012입니다. 대부분의 호출은 1단위입니다. `limit`이 한 페이지를 넘으면 페이지마다 1단위이며,
  오퍼레이션별 페이지에 범위가 나와 있습니다.

## 에러

다른 API와 같은 응답 형식과 코드를 씁니다. [Errors](/docs/errors)를 보세요. 없는 장소나 앱은 `404 NOT_FOUND`, 없는 상품은
`404 PRODUCT_NOT_FOUND`를 돌려주며, 메시지에 그 id가 나옵니다. 한 상점의 Google Shopping 상품에는 리뷰가 없어
`404 REVIEWS_NOT_FOUND`를 돌려줍니다.

## 참고

- [Response Schema](/docs/api-reference/serp/response-schema): 모든 타입의 모든 필드
- [AI Answers API](/docs/api-reference/answers): ChatGPT, Gemini, Google AI Mode 등을 답변 타입 하나로
- [Errors](/docs/errors): 모든 에러 코드