Google Web Search — API 레퍼런스

POST

사용 가능

/google/search

Search

q, 언어 hl, 국가 gl 및 지원 기기로 Google 웹을 검색합니다. 결과 영역은 쿼리와 원본 응답에 따라 다릅니다.

type

result

organic

과금

1 credits

q, 언어 hl, 국가 gl 및 지원 기기로 Google 웹을 검색합니다. 결과 영역은 쿼리와 원본 응답에 따라 다릅니다.

파라미터

필드타입제공 조건설명

q

필수

string

필수

검색 쿼리 문자열입니다.

hl

선택

string

선택

언어 코드입니다. 기본값은 en입니다.

gl

선택

string

선택

국가 코드입니다. 기본값은 us입니다.

page

선택

number

선택

1부터 시작하는 페이지 번호입니다. 기본값은 1입니다.

device

선택

"default" | "pc" | "mobile"

선택

Google Search에만 적용됩니다. default는 자동 라우팅, pc는 데스크톱 세션, mobile은 모바일 세션을 사용합니다.

json

{
  "device": "mobile",
  "gl": "us",
  "hl": "en",
  "q": "coffee shops"
}

Playground에서 실행

응답 필드

필드타입제공 조건설명

query

필수

string

필수

요청에서 정규화된 쿼리입니다.

page

필수

number

필수

현재 페이지 번호입니다. 1부터 시작합니다.

organic

선택

OrganicResult[]

일반 검색 결과가 파싱된 경우.

일반 검색 결과.

featured_snippet

선택

FeaturedSnippet

Google이 추천 스니펫을 표시하는 경우.

일반 결과와 별도로 반환되는 추천 스니펫 답변 카드.

top_stories

선택

TopStory[]

검색 결과에 주요 뉴스가 있는 경우.

주요 뉴스 모듈.

people_also_ask

선택

PAA[]

관련 검색어.

OrganicResult 결과 항목 구조

필드타입제공 조건설명

rank

필수

number

필수

이 응답 안에서 1부터 시작하는 순위입니다.

position

선택

number

제공되는 경우 rank의 별칭입니다.

position 필드를 기대하는 클라이언트용 정규화 순위입니다.

title

필수

string

필수

결과 제목입니다.

link

필수

string

필수

파서가 반환하는 기본 링크입니다.

url

선택

string

결과 링크를 정규화할 수 있을 때 반환됩니다.

정규화된 대상 URL이며 보통 link와 같습니다.

source_url

선택

string

Google 리다이렉트/원본 URL이 관측된 경우에만 반환됩니다.

디버깅과 출처 확인을 위해 보존되는 원본 Google URL입니다.

display_url

선택

string

Google 표시 텍스트나 도메인을 추출할 수 있을 때 반환됩니다.

표시 URL 또는 출처 도메인입니다.

display_link

선택

string

Google 표시 텍스트가 있는 경우.

Google 표시 링크 원문.

snippet

선택

string

스니펫이 파싱된 경우.

일반 검색 결과 요약.

date

선택

string

Google 스니펫에 날짜가 있는 경우.

스니펫에서 추출한 날짜 원문.

published_at

선택

string

파싱된 날짜가 있으면 해당 별칭.

정규화된 날짜 별칭.

icon

선택

string

파비콘/이미지가 제공되는 경우.

결과 아이콘 URL.

sitelinks

선택

{ title, link, url, source_url?, display_url? }[]

사이트 링크가 있는 경우.

일반 결과에 속하는 중첩 사이트 링크.

코드 및 응답 예시

bash

curl -X POST 'https://api.serpbase.dev/google/search' \
  -H "Content-Type: application/json" \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"device":"mobile","gl":"us","hl":"en","q":"coffee shops"}'

기존 Google 요청 예시

bash

curl -X POST https://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,
    "device": "default"
  }'

참고

검색 grounding, SEO 확인, 답변 추출.

검색 결과에 해당 모듈이 있으면 ai_overview, weather, finance, flight, result_stats도 반환됩니다.