빠른 답변
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). 지역을 참조하세요. |
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
{
"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 -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=desktopimport 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"])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
{
"credits_remaining": 84210,
"credits_used_today": 1290,
"concurrency_limit": 10
}코드 예시
curl -s "https://serpcrypto.com/api/v1/credits" \
-H "Authorization: Bearer $SERPCRYPTO_API_KEY"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"])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": "…"}}입니다. 오류 페이지에서 각 오류를 설명하고 재시도 코드를 보여줍니다.
| 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 검색입니다. 가격을 참고하세요.
검색 쿼리는 어떻게 인코딩해야 하나요?
다른 쿼리 문자열 값과 마찬가지로 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을 반환하고 크레딧을 쓰지 않습니다. 가격 페이지에서 잔액으로 다른 팩을 구매하세요. API 키는 계속 작동하고 검색은 곧바로 다시 시작됩니다.
같은 키를 여러 서버에서 사용할 수 있나요?
네. 키는 IP 주소에 묶이지 않습니다. 제한되는 것은 계정에서 동시에 실행되는 검색 수이며, GET /credits에서 concurrency_limit이 그 수치를 알려줍니다.