# SERP API 레퍼런스: GET /search 및 GET /credits

> SerpCrypto SERP API 레퍼런스: GET /search 파라미터, 엔진, 기본값, 응답 블록, 에러 코드 및 GET /credits를 curl, Python, Node.js로 안내합니다.

- URL: https://serpcrypto.com/ko/docs/search/
- 마지막 업데이트: 2026-10-22
- 발행자: SerpCrypto (https://serpcrypto.com)

SerpCrypto API 버전 1의 모든 파라미터, 기본값, 에러 코드입니다. 기본 URL: `https://serpcrypto.com/api/v1`. 모든 요청은 HTTPS를 사용하며, 모든 응답은 UTF-8 인코딩의 JSON입니다.

**빠른 답변 — SerpCrypto 검색 엔드포인트는 어떤 파라미터를 받나요?**

`GET https://serpcrypto.com/api/v1/search`는 필수 파라미터 하나인 `q`와 선택 파라미터 아홉 개인 `engine`, `gl`, `hl`, `location`, `google_domain`, `device`, `page`, `safe`, `period`를 받습니다. **SerpCrypto**은 JSON을 반환하고 모든 6 엔진에서 성공한 검색당 1 크레딧을 차감하며, 오류는 무료입니다. 팩은 검색 10,000회 기준 US$7.50부터 시작하며, KYC 없이 암호화폐로 결제합니다.

## 인증은 어떻게 하나요?

키를 두 가지 방법 중 하나로 보내세요. 권장 방법은 헤더 `Authorization: Bearer YOUR_KEY`입니다. 다른 방법은 검색 쿼리 파라미터 `api_key=YOUR_KEY`이며, 브라우저 탭에서 빠르게 테스트할 때 편리합니다.

키가 없거나 틀리거나 폐기된 경우 `401 invalid_api_key`을 받고 아무것도 차감되지 않습니다. 대시보드에서 언제든지 생성하고 폐기할 수 있는 API 키, 따라서 각 스크립트나 서버에 고유한 키를 부여하고 다른 키는 건드리지 않고 하나만 폐기할 수 있습니다.

## 검색 실행

`GET /api/v1/search`

선택한 엔진에서 검색을 한 번 실행하고 결과 페이지를 JSON으로 반환합니다. 성공한 검색은 엔진에 관계없이 1 크레딧을 사용하고, 오류는 사용하지 않습니다. 파라미터는 URL 인코딩된 검색 쿼리로 전달됩니다. 예시는 Google에 텍사스 오스틴의 커피 로스터를 요청하며, ID, 개수, 결과는 설명용입니다.

인증: `Authorization: Bearer API_KEY` 헤더의 API 키.

**파라미터**

| 이름 | 위치 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- | --- |
| `q` | query | string | 예 | 사람이 입력하듯 작성된 검색 쿼리입니다. 따옴표나 `site:` 같은 검색 연산자도 검색 쿼리의 일부입니다. |
| `engine` | query | string | 아니요 | `google` (기본값), `google_news`, `google_images`, `google_maps`, `google_shopping` 또는 `bing`. |
| `gl` | query | string | 아니요 | 결과 국가: 소문자로 된 ISO 3166-1 alpha-2 코드(예: `us`, `de`, `br`). 기본값 `us`. |
| `hl` | query | string | 아니요 | 인터페이스 언어(예: `en`, `de`, `pt-BR`). 기본값 `en`. |
| `location` | query | string | 아니요 | 도시 단위 지역으로 `City, Region, Country` 형태로 표기합니다(예: `Austin, Texas, United States`). [지역](https://serpcrypto.com/ko/docs/locations/)을 참조하세요. |
| `google_domain` | query | string | 아니요 | 검색할 Google 도메인입니다(예: `google.de`). 기본값은 `gl` 국가의 도메인입니다. `engine=bing`일 때는 무시됩니다. |
| `device` | query | string | 아니요 | `desktop`(기본값) 또는 `mobile`. |
| `page` | query | integer | 아니요 | 1(기본값)부터 10까지의 결과 페이지입니다. 각 페이지는 별도의 검색이며 크레딧 1개를 사용합니다. |
| `safe` | query | string | 아니요 | `active`은 선정적인 결과를 필터링하고, `off`(기본값)은 필터링하지 않습니다. |
| `period` | query | string | 아니요 | 지난 1시간(`h`), 하루(`d`), 일주일(`w`), 한 달(`m`) 또는 1년(`y`) 이내의 결과만. |
| `api_key` | query | string | 아니요 | `Authorization` 헤더를 보내지 않는 경우 사용할 API 키입니다. |

**응답** `200`

```json
{
  "search_metadata": {
    "id": "srch_7f3a9c2e41b8",
    "status": "success",
    "engine": "google",
    "created_at": "2026-10-22T09:14:05Z",
    "credits_used": 1
  },
  "search_parameters": {
    "engine": "google",
    "q": "coffee roasters",
    "gl": "us",
    "hl": "en",
    "location": "Austin, Texas, United States",
    "google_domain": "google.com",
    "device": "desktop",
    "page": 1
  },
  "search_information": {
    "total_results": 18600000,
    "query_displayed": "coffee roasters"
  },
  "local_results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "123 Example St, Austin, TX",
      "rating": 4.7,
      "reviews": 312,
      "type": "Coffee roasters"
    }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 best coffee roasters in Austin",
      "link": "https://www.example.com/austin/coffee-roasters",
      "displayed_link": "www.example.com › austin › coffee",
      "snippet": "From light Nordic roasts to dark espresso blends, these local roasters…",
      "date": "Sep 30, 2026"
    },
    {
      "position": 2,
      "title": "Example Roasting Co. | Fresh beans, roasted in Austin",
      "link": "https://www.example.org/",
      "displayed_link": "www.example.org",
      "snippet": "Small-batch coffee roasted every weekday and shipped the same day…"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the oldest coffee roaster in Austin?",
      "snippet": "…",
      "title": "Austin coffee history",
      "link": "https://www.example.net/austin-coffee-history"
    }
  ],
  "related_searches": [
    {
      "query": "coffee roasters near me"
    },
    {
      "query": "coffee roasters austin wholesale"
    }
  ],
  "pagination": {
    "current": 1,
    "next_page": 2
  }
}
```

*curl*

```bash
curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=coffee roasters" \
  --data-urlencode "location=Austin, Texas, United States" \
  -d gl=us -d hl=en -d device=desktop
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/search",
    params={
        "q": "coffee roasters",
        "location": "Austin, Texas, United States",
        "gl": "us",
        "hl": "en",
    },
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json()["organic_results"][0]["link"])
```

*Node.js*

```javascript
const params = new URLSearchParams({
  q: "coffee roasters",
  location: "Austin, Texas, United States",
  gl: "us",
  hl: "en",
});
const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const data = await res.json();
console.log(data.organic_results?.[0]?.link);
```

## 어떤 engine 값이 있으며, 각각 무엇을 반환하나요?

프레임(`search_metadata`, `search_parameters`, `search_information`)은 모든 engine에서 동일합니다. 블록은 페이지에 표시될 때만 나타납니다.

| `engine` | 출처 | 답변의 주요 블록 |
| --- | --- | --- |
| `google` | Google Search | `ai_overview`, `organic_results`, `ads`, `people_also_ask`, `local_results`, `knowledge_graph`, `top_stories`, `inline_videos`, `shopping_results`, `related_searches`, `pagination` |
| `google_news` | Google News | `news_results`: 제목, 링크, 출처, 날짜, 스니펫, 썸네일 |
| `google_images` | Google Images | `images_results`: 원본 URL과 크기, 썸네일, 출처 페이지 |
| `google_maps` | Google Maps | `local_results`: 이름, 주소, 전화번호, 웹사이트, 평점, 리뷰, 카테고리, 영업시간, 좌표 |
| `google_shopping` | Google Shopping | `shopping_results`: 제목, 가격, 추출된 가격, 통화, 판매처, 배송, 평점 |
| `bing` | Bing | `organic_results`, `related_searches` |

## 크레딧 조회

`GET /api/v1/credits`

계정에 남은 크레딧, UTC 자정 이후 사용한 크레딧, 계정에서 동시에 실행할 수 있는 검색 수를 반환합니다. 이 호출은 무료입니다. 아래 값은 예시입니다.

인증: `Authorization: Bearer API_KEY` 헤더의 API 키.

**응답** `200`

```json
{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}
```

*curl*

```bash
curl -s "https://serpcrypto.com/api/v1/credits" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY"
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/credits",
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["credits_remaining"])
```

*Node.js*

```javascript
const res = await fetch("https://serpcrypto.com/api/v1/credits", {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const { credits_remaining } = await res.json();
console.log(credits_remaining);
```

## API가 반환할 수 있는 오류는 무엇인가요?

모든 오류의 본문은 `{"error": {"code": "…", "message": "…"}}`입니다. [오류 페이지](https://serpcrypto.com/ko/docs/errors/)에서 각 오류를 설명하고 재시도 코드를 보여줍니다.

| HTTP | `code` | 발생 시점 | 과금 여부 |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | 필수 parameter가 없거나 값이 허용 목록을 벗어남 | 아니요 |
| 401 | `invalid_api_key` | API 키가 없거나 잘못되었거나 폐기됨 | 아니요 |
| 402 | `insufficient_credits` | 계정에 남은 크레딧이 없음 | 아니요 |
| 429 | `concurrency_limit` | 계정에서 동시에 실행 중인 검색이 너무 많음 | 아니요 |
| 502 | `search_failed` | 이 요청에 대해 engine 또는 수집이 실패함. 다시 시도하세요 | 아니요 |
| 504 | `search_timeout` | 제한 시간 내에 응답이 없음. 다시 시도하세요 | 아니요 |

## 정확히 무엇이 과금되나요?

- **검색 1회 성공 = 크레딧 1개**, Google Maps와 Google Shopping을 포함한 모든 engine에서 동일합니다.
- **각 결과 페이지는 검색 1회입니다.** 페이지당 약 10개의 유기적 결과로, Google이 2025년 9월 num=100을 더 이상 지원하지 않게 된 이후 제공되는 방식입니다. 추가 페이지마다 크레딧이 1개 더 차감됩니다.
- **오류는 무료입니다:** HTTP 상태 코드가 200이 아닌 모든 응답은 크레딧을 사용하지 않습니다.
- **크레딧 조회는 무료입니다.**

선불 검색 크레딧은 만료되지 않습니다: 사용하지 않은 검색은 사용할 때까지 계정에 남아 있습니다. 팩은 US$7.50에서 검색 10,000회까지이며, 가장 큰 팩은 US$0.30/1K 검색입니다. [가격](https://serpcrypto.com/ko/pricing/)을 참고하세요.

## 검색 쿼리는 어떻게 인코딩해야 하나요?

다른 쿼리 문자열 값과 마찬가지로 `q`을 URL 인코딩하여 보내세요. 공백은 `%20` 또는 `+`이 되고, 악센트가 있는 문자는 UTF-8로 인코딩됩니다. curl은 `--data-urlencode`으로, Python `requests`과 `httpx`는 `params=`으로, Node.js는 `URLSearchParams`로 처리합니다.

검색 쿼리는 사람이 검색창에 입력할 때와 똑같이 작성하세요. 따옴표, 빼기 기호, `site:`은 `q` 안에 그대로 둡니다. 방문자에게 적용할 때와 마찬가지로 engine이 이를 어떻게 적용할지 결정합니다.

## API는 버전 관리가 되나요?

예. 버전은 경로의 일부입니다: `/api/v1/`. 새 field나 block이 버전 1 응답에 나타날 수 있으므로, 코드는 알지 못하는 키를 무시해야 합니다. field를 제거하거나 이름을 바꾸는 경우 `v1`에 대한 변경이 아니라 경로에 새 버전이 추가됩니다.

## API 레퍼런스 관련 질문

### JSON 본문으로 POST 요청을 보낼 수 있나요?

버전 1에서는 안 됩니다. 두 endpoint 모두 쿼리 문자열에 파라미터를 담아 GET 요청을 받습니다. 덕분에 모든 호출을 curl이나 브라우저로 쉽게 재현할 수 있고, 본문 없이도 쉽게 로그를 남길 수 있습니다.

### 검색 한 번에 결과가 몇 개 반환되나요?

페이지당 약 10개의 유기적 결과로, Google이 2025년 9월 num=100을 더 이상 지원하지 않게 된 이후 제공되는 방식입니다. 추가 페이지마다 크레딧이 1개 더 차감됩니다. 결과 30개를 모으려면 `page=1`, `page=2`, `page=3`을 요청하세요. 검색 세 번, 크레딧 세 개입니다.

### 크레딧이 떨어지면 어떻게 되나요?

그다음 검색은 `402 insufficient_credits`을 반환하고 크레딧을 쓰지 않습니다. [가격 페이지](https://serpcrypto.com/ko/pricing/)에서 잔액으로 다른 팩을 구매하세요. API 키는 계속 작동하고 검색은 곧바로 다시 시작됩니다.

### 같은 키를 여러 서버에서 사용할 수 있나요?

네. 키는 IP 주소에 묶이지 않습니다. 제한되는 것은 계정에서 동시에 실행되는 검색 수이며, `GET /credits`에서 `concurrency_limit`이 그 수치를 알려줍니다.

---

SerpCrypto: SerpCrypto는 개발자와 AI 에이전트를 위한 SERP API로, Google 및 Bing 검색 결과를 JSON으로 반환하며 신분증 업로드 없이 암호화폐로 결제합니다. 선불 검색 크레딧 US$0.30/1K 검색는 만료되지 않습니다. KYC 없이 — 신분증도, 셀피도, 서류도 없습니다. 암호화폐 결제.