POST JSON 요청을 보내고 X-API-Key 헤더에 API key를 전달합니다. 성공과 실패 모두 JSON 본문을 반환합니다.
공통 응답 구조
성공 요청당 1 또는 2 크레딧
support trace id
curl -X POST https://test-api.serpbase.dev/google/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"q":"openai realtime api","hl":"en","gl":"us"}'성공 응답은 동일한 최상위 메타데이터를 반환합니다. 엔드포인트별 데이터는 organic, images, news, videos, places, place 같은 결과 키에 들어갑니다.
statusnumber필수
비즈니스 상태 코드입니다. 0은 성공을 의미합니다.
request_idstring필수
지원, 재시도, 로그 추적에 사용하는 요청 ID입니다.
elapsed_msnumber필수
게이트웨이가 측정한 요청 지연 시간(ms)입니다.
credits_chargednumber필수
환불 로직 적용 후 차감된 크레딧입니다.
search_typestring필수
확정된 타입: search, images, news, videos, maps_search, maps_detail.
/google/searchGoogle 스타일의 자연 검색 결과와 SERP 모듈입니다.
/google/images이미지 URL, 썸네일, 출처 페이지, 도메인.
/google/news게시자, 시간, 스니펫, 썸네일이 포함된 뉴스 기사.
/google/videos출처, 길이, 시간, 썸네일이 포함된 동영상 결과.
/google/maps/search좌표, 연락처, 카테고리, 영업시간, 사진을 포함하는 로컬 장소 검색.
/google/maps/detailGoogle Maps feature_id로 단일 장소 상세 정보를 가져옵니다.
/google/searchSearch
Google 스타일의 자연 검색 결과와 SERP 모듈입니다.
qstring필수
검색 쿼리 문자열입니다.
hlstring선택
언어 코드입니다. 기본값은 en입니다.
glstring선택
국가 코드입니다. 기본값은 us입니다.
pagenumber선택
1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.
querystring필수
요청에서 정규화된 쿼리입니다.
pagenumber필수
현재 페이지 번호입니다. 1부터 시작합니다.
organicOrganicResult[]When organic results are parsed.
Organic search results.
top_storiesTopStory[]When the SERP contains top stories.
Top stories module.
people_also_askPAA[]When People Also Ask is present.
Question, answer, and source links.
knowledge_graphKnowledgeGraphWhen a knowledge panel is parsed.
Entity panel data.
related_searchesstring[]When related search suggestions are found.
Related search queries.
ranknumber필수
이 응답 안에서 1부터 시작하는 순위입니다.
positionnumber제공되는 경우 rank의 별칭입니다.
position 필드를 기대하는 클라이언트용 정규화 순위입니다.
titlestring필수
결과 제목입니다.
linkstring필수
파서가 반환하는 기본 링크입니다.
urlstring결과 링크를 정규화할 수 있을 때 반환됩니다.
정규화된 대상 URL이며 보통 link와 같습니다.
source_urlstringGoogle 리다이렉트/원본 URL이 관측된 경우에만 반환됩니다.
디버깅과 출처 확인을 위해 보존되는 원본 Google URL입니다.
display_urlstringGoogle 표시 텍스트나 도메인을 추출할 수 있을 때 반환됩니다.
표시 URL 또는 출처 도메인입니다.
display_linkstringWhen Google display text is present.
Raw Google display link text.
snippetstringWhen a snippet is parsed.
Organic result summary.
datestringWhen Google includes a date in the snippet.
Raw date text extracted from snippet.
published_atstringAlias for parsed date when available.
Normalized date alias.
iconstringWhen a favicon/image is exposed.
Result icon URL.
sitelinks{ title, link, url, source_url?, display_url? }[]When sitelinks are present.
Nested sitelinks for the organic result.
curl -X POST https://test-api.serpbase.dev/google/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "python asyncio",
"hl": "en",
"gl": "us",
"page": 1
}'검색 grounding, SEO 확인, 답변 추출.
Search can also return ai_overview, weather, finance, flight, and result_stats when those modules appear in the SERP.
/google/images이미지 검색
이미지 URL, 썸네일, 출처 페이지, 도메인.
qstring필수
검색 쿼리 문자열입니다.
hlstring선택
언어 코드입니다. 기본값은 en입니다.
glstring선택
국가 코드입니다. 기본값은 us입니다.
pagenumber선택
1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.
querystring필수
요청에서 정규화된 쿼리입니다.
pagenumber필수
현재 페이지 번호입니다. 1부터 시작합니다.
imagesImageResult[]When image results are parsed.
Google Images results.
ranknumber필수
이 응답 안에서 1부터 시작하는 순위입니다.
positionnumber제공되는 경우 rank의 별칭입니다.
position 필드를 기대하는 클라이언트용 정규화 순위입니다.
titlestring이미지 제목 또는 alt 텍스트를 파싱할 수 있을 때 반환됩니다.
결과 제목입니다.
linkstring필수
파서가 반환하는 기본 링크입니다.
urlstring결과 링크를 정규화할 수 있을 때 반환됩니다.
정규화된 대상 URL이며 보통 link와 같습니다.
source_urlstringGoogle 리다이렉트/원본 URL이 관측된 경우에만 반환됩니다.
디버깅과 출처 확인을 위해 보존되는 원본 Google URL입니다.
display_urlstringGoogle 표시 텍스트나 도메인을 추출할 수 있을 때 반환됩니다.
표시 URL 또는 출처 도메인입니다.
image_urlstring필수
Full image URL.
thumbnail_urlstringGoogle이 썸네일을 제공할 때 반환됩니다.
썸네일 URL입니다.
thumbnailstring제공되는 경우 thumbnail_url의 별칭입니다.
정규화된 썸네일 별칭입니다.
sourcestringWhen source text is parsed.
Image source label.
domainstringWhen source page domain can be derived.
Source page domain.
curl -X POST https://test-api.serpbase.dev/google/images \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "iphone 15 pro blue",
"hl": "en",
"gl": "us",
"page": 1
}'비주얼 검색, 상품 모니터링, 이미지 출처 탐색.
Some Google Images payload shapes expose rank/link but not every normalized alias. Treat url, display_url, source_url, position, and thumbnail as optional.
/google/news뉴스 검색
게시자, 시간, 스니펫, 썸네일이 포함된 뉴스 기사.
qstring필수
검색 쿼리 문자열입니다.
hlstring선택
언어 코드입니다. 기본값은 en입니다.
glstring선택
국가 코드입니다. 기본값은 us입니다.
pagenumber선택
1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.
querystring필수
요청에서 정규화된 쿼리입니다.
pagenumber필수
현재 페이지 번호입니다. 1부터 시작합니다.
newsNewsResult[]When news results are parsed.
Google News results.
ranknumber필수
이 응답 안에서 1부터 시작하는 순위입니다.
positionnumber제공되는 경우 rank의 별칭입니다.
position 필드를 기대하는 클라이언트용 정규화 순위입니다.
titlestring필수
결과 제목입니다.
linkstring필수
파서가 반환하는 기본 링크입니다.
urlstring결과 링크를 정규화할 수 있을 때 반환됩니다.
정규화된 대상 URL이며 보통 link와 같습니다.
source_urlstringGoogle 리다이렉트/원본 URL이 관측된 경우에만 반환됩니다.
디버깅과 출처 확인을 위해 보존되는 원본 Google URL입니다.
display_urlstringGoogle 표시 텍스트나 도메인을 추출할 수 있을 때 반환됩니다.
표시 URL 또는 출처 도메인입니다.
sourcestringWhen publisher text is parsed.
Publisher/source label.
timestringWhen Google exposes time text.
Raw published time text.
published_atstringAlias for parsed time when available.
Normalized published time alias.
snippetstringWhen a snippet is parsed.
Article summary snippet.
thumbnail_urlstringGoogle이 썸네일을 제공할 때 반환됩니다.
썸네일 URL입니다.
thumbnailstring제공되는 경우 thumbnail_url의 별칭입니다.
정규화된 썸네일 별칭입니다.
curl -X POST https://test-api.serpbase.dev/google/news \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "apple event",
"hl": "en",
"gl": "us",
"page": 1
}'브랜드 모니터링, 트렌드 추적, 미디어 탐색.
Source and time are parsed from compact Google metadata text, so clients should treat both as optional.
/google/videos동영상 검색
출처, 길이, 시간, 썸네일이 포함된 동영상 결과.
qstring필수
검색 쿼리 문자열입니다.
hlstring선택
언어 코드입니다. 기본값은 en입니다.
glstring선택
국가 코드입니다. 기본값은 us입니다.
pagenumber선택
1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.
querystring필수
요청에서 정규화된 쿼리입니다.
pagenumber필수
현재 페이지 번호입니다. 1부터 시작합니다.
videosVideoResult[]When video results are parsed.
Google Videos results.
ranknumber필수
이 응답 안에서 1부터 시작하는 순위입니다.
positionnumber제공되는 경우 rank의 별칭입니다.
position 필드를 기대하는 클라이언트용 정규화 순위입니다.
titlestring필수
결과 제목입니다.
linkstring필수
파서가 반환하는 기본 링크입니다.
urlstring결과 링크를 정규화할 수 있을 때 반환됩니다.
정규화된 대상 URL이며 보통 link와 같습니다.
source_urlstringGoogle 리다이렉트/원본 URL이 관측된 경우에만 반환됩니다.
디버깅과 출처 확인을 위해 보존되는 원본 Google URL입니다.
display_urlstringGoogle 표시 텍스트나 도메인을 추출할 수 있을 때 반환됩니다.
표시 URL 또는 출처 도메인입니다.
sourcestringWhen source/channel can be parsed.
Video source or channel label.
durationstringWhen duration appears in result text.
Video duration text.
timestringWhen posted time can be parsed.
Raw posted time text.
published_atstringAlias for parsed time when available.
Normalized posted time alias.
thumbnail_urlstringGoogle이 썸네일을 제공할 때 반환됩니다.
썸네일 URL입니다.
thumbnailstring제공되는 경우 thumbnail_url의 별칭입니다.
정규화된 썸네일 별칭입니다.
curl -X POST https://test-api.serpbase.dev/google/videos \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "python asyncio tutorial",
"hl": "en",
"gl": "us",
"page": 1
}'동영상 검색, 튜토리얼 탐색, 미디어 모니터링.
If no dedicated video cards are parsed, the parser falls back to news-style extraction for compatible Google layouts.
/google/maps/search지도 검색
좌표, 연락처, 카테고리, 영업시간, 사진을 포함하는 로컬 장소 검색.
qstring필수
검색 쿼리 문자열입니다.
hlstring선택
언어 코드입니다. 기본값은 en입니다.
glstring선택
국가 코드입니다. 기본값은 us입니다.
pagenumber선택
1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.
latnumber선택
지도 중심 위도입니다. lng와 함께 보내야 합니다.
lngnumber선택
지도 중심 경도입니다. lat와 함께 보내야 합니다.
zoomnumber선택
지도 줌 레벨입니다. 1부터 21까지이며 좌표가 있으면 기본값은 14입니다.
querystring필수
요청에서 정규화된 쿼리입니다.
pagenumber필수
현재 페이지 번호입니다. 1부터 시작합니다.
placesMapsPlace[]When local places are parsed.
Local place results.
positionnumberMaps Search only.
Place rank in the local result list.
namestring필수
Place name.
titlestring필수
Alias for name.
feature_idstring필수
Google Maps feature id.
place_idstringWhen Google exposes it.
Google place id.
data_idstringAlias for feature_id.
Maps data id.
cidstringDerived from feature_id when possible.
Google CID.
kgmidstringWhen present in Maps payload.
Knowledge graph machine id.
google_maps_urlstringWhen Google exposes a Maps URL.
Google Maps URL.
urlstringgoogle_maps_url or website fallback.
Primary place URL.
ratingnumberWhen rating is present.
Google rating.
typesstring[]When categories are present.
Place type labels.
categoryobjectWhen category block is parsed.
Structured category data.
addressstringWhen address is present.
Formatted address.
address_componentsobjectWhen components are present.
Street, city, postal code, country code.
plus_codeobjectWhen plus code is present.
Global and compound plus codes.
phonestringWhen phone is present.
Local phone number.
phone_internationalstringWhen present.
International phone number.
phone_uristringWhen present.
Telephone URI.
websitestringWhen website is present.
Business website.
website_domainstringWhen website domain is present.
Business website domain.
latitudenumberWhen coordinates are present.
Latitude.
longitudenumberWhen coordinates are present.
Longitude.
imagestringWhen image is present.
Primary place image.
thumbnailstringAlias for image when available.
Primary image alias.
photosMapsPhoto[]When photos are parsed.
Photo id, URL, size, and optional coordinates.
hoursRecord<string,string>When hours are parsed.
Opening hours by day.
open_statusobjectWhen status is present.
Open status text and current hours.
attributesobject[]When attributes are parsed.
Grouped place attributes.
related_placesobject[]When related places are present.
Related places from Maps payload.
short_descriptionstringWhen description block is present.
Short place description.
descriptionstringWhen description block is present.
Longer place description.
snippetstringshort_description or description fallback.
Normalized text summary.
timezonestringWhen present.
Place timezone.
regionstringWhen present.
Region label.
country_codestringWhen present.
Country code.
languagestringWhen present.
Language code from Maps payload.
curl -X POST https://test-api.serpbase.dev/google/maps/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "coffee",
"hl": "en",
"gl": "us",
"page": 1,
"lat": 37.7749,
"lng": -122.4194,
"zoom": 14
}'로컬 탐색, 매장 조회, 지역별 감사.
lat and lng must be sent together. zoom is valid only with coordinates and defaults to 14.
/google/maps/detail지도 상세
Google Maps feature_id로 단일 장소 상세 정보를 가져옵니다.
feature_idstring필수
Google Maps feature id입니다. 형식은 0x...:0x... 입니다.
hlstring선택
언어 코드입니다. 기본값은 en입니다.
glstring선택
국가 코드입니다. 기본값은 us입니다.
feature_idstring필수
Feature id resolved from the Maps detail request.
pagenumber필수
Always 1 for maps detail.
placeMapsPlaceWhen place details are parsed.
Single place detail object.
positionnumberMaps Search only.
Place rank in the local result list.
namestring필수
Place name.
titlestring필수
Alias for name.
feature_idstring필수
Google Maps feature id.
place_idstringWhen Google exposes it.
Google place id.
data_idstringAlias for feature_id.
Maps data id.
cidstringDerived from feature_id when possible.
Google CID.
kgmidstringWhen present in Maps payload.
Knowledge graph machine id.
google_maps_urlstringWhen Google exposes a Maps URL.
Google Maps URL.
urlstringgoogle_maps_url or website fallback.
Primary place URL.
ratingnumberWhen rating is present.
Google rating.
typesstring[]When categories are present.
Place type labels.
categoryobjectWhen category block is parsed.
Structured category data.
addressstringWhen address is present.
Formatted address.
address_componentsobjectWhen components are present.
Street, city, postal code, country code.
plus_codeobjectWhen plus code is present.
Global and compound plus codes.
phonestringWhen phone is present.
Local phone number.
phone_internationalstringWhen present.
International phone number.
phone_uristringWhen present.
Telephone URI.
websitestringWhen website is present.
Business website.
website_domainstringWhen website domain is present.
Business website domain.
latitudenumberWhen coordinates are present.
Latitude.
longitudenumberWhen coordinates are present.
Longitude.
imagestringWhen image is present.
Primary place image.
thumbnailstringAlias for image when available.
Primary image alias.
photosMapsPhoto[]When photos are parsed.
Photo id, URL, size, and optional coordinates.
hoursRecord<string,string>When hours are parsed.
Opening hours by day.
open_statusobjectWhen status is present.
Open status text and current hours.
attributesobject[]When attributes are parsed.
Grouped place attributes.
related_placesobject[]When related places are present.
Related places from Maps payload.
short_descriptionstringWhen description block is present.
Short place description.
descriptionstringWhen description block is present.
Longer place description.
snippetstringshort_description or description fallback.
Normalized text summary.
timezonestringWhen present.
Place timezone.
regionstringWhen present.
Region label.
country_codestringWhen present.
Country code.
languagestringWhen present.
Language code from Maps payload.
curl -X POST https://test-api.serpbase.dev/google/maps/detail \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"feature_id": "0x8085809c2c6fdc63:0x4b3f2d70e4f5a123",
"hl": "en",
"gl": "us"
}'장소 정보 보강, 로컬 CRM 데이터, 상세 페이지.
Use feature_id from Maps Search results to request a detail record.
errorstring필수
사람이 읽을 수 있는 오류 메시지입니다.
Request completed successfully.
Missing or invalid body or parameters.
Missing, invalid, or revoked API key.
Account balance is not enough.
QPS or concurrency limit exceeded.
Unexpected internal server error.
Worker returned an upstream fetch or parse error.
No worker session is available.
Gateway timed out waiting for a worker result.
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}