Google 검색 결과 API (GOOGLE_SERP) - querying.ai

GOOGLE_SERP는 google.com 결과 페이지 하나를 불러와 자연 검색 결과와 패널을 반환합니다. AI 개요를 기다리지 않으므로 GOOGLE보다 빠르게 답하고 비용도 적습니다. 순위 추적에 쓰거나, WEB_SCRAPE로 읽을 페이지를 찾을 때 쓰세요.


`taskType`	`GOOGLE_SERP`
입력	`query`(필수), `page`, `country`, `location`, `include`
크레딧	태스크당 1
국가	기본값 `US`. 모든 ISO 3166-1 alpha-2 코드를 받습니다.
위치	지원합니다. 지역과 위치를 참고하세요.

요청

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "GOOGLE_SERP", "payload": { "query": "best running shoes for flat feet", "country": "US", "page": 2 } }'

태스크는 비동기로 실행됩니다. 결과는 비동기 태스크에 설명한 방법으로 읽으세요.

파라미터

필드	필수	설명
`query`	예	검색어, 1~100,000자. `query`가 없으면 `prompt`를 받습니다.
`page`	아니요	결과 페이지, 1~10의 정수. 기본값은 `1`입니다. 페이지마다 자연 검색 결과 10건이 담깁니다. 다른 값은 `422 VALIDATION_ERROR`를 반환합니다.
`country`	아니요	검색할 Google 시장. 기본값은 `US`입니다.
`location`	아니요	십진 도 단위의 `{ "latitude", "longitude" }`. Google은 그 지점에 있는 사용자에게 답하듯 답하고, 결과의 `location`에 같은 지점을 돌려줍니다.
`include.rawResponse`	아니요	`true`면 결과 페이지 HTML을 `rawContent`로 더합니다. 페이지가 커서 1MB 가까이 되는 경우가 많습니다.

응답

예를 들어 한 검색어의 2페이지는 다음과 같습니다.

{
  "organicResults": [
    { "position": 11, "title": "...", "link": "https://...", "displayedLink": "...", "snippet": "...", "page": 2 }
  ],
  "peopleAlsoAsk": [{ "...": "..." }],
  "relatedSearches": [{ "...": "..." }],
  "ads": [{ "...": "..." }],
  "page": 2
}

필드	설명
`organicResults`	항상 있습니다. `position`은 페이지를 넘어 이어서 세므로 2페이지 첫 결과는 `11`입니다. 모든 행에 출처 페이지 `page`가 붙습니다.
`page`	불러온 페이지.
`peopleAlsoAsk`, `relatedSearches`, `knowledgeGraph`	페이지에 있을 때 Google의 패널.
`ads`	페이지에 있을 때 상단과 하단 광고.
`map`	페이지에 있을 때 로컬 팩. 장소마다 `name`, `position`, `placeId`, `location`, `mapsUrl`, `reviews` 등이 담깁니다.
`serp`	있을 때 그 밖의 패널: `topStories`, `videoResults`, `localMap`, `discussionsAndForums`.
`location`	보낸 경우 보낸 지점.
`rawContent`	`include.rawResponse: true`일 때 결과 페이지 HTML.

페이지에 없는 패널은 null이나 []로 보내지 않고 생략합니다. organicResults와 page를 제외한 모든 필드를 선택 필드로 다루세요. aioverview, text, sources는 없습니다. AI 개요는 GOOGLE을 쓰세요.

제한과 오류

완료된 태스크의 organicResults가 비어 있으면 Google 자체가 그 검색어에 결과를 내지 않았다는 뜻입니다. 반환하기 전에 다른 브라우저에서 한 번 더 확인합니다.
1~10을 벗어난 page는 422 VALIDATION_ERROR를 반환합니다.
형식이 잘못된 location은 400 VALIDATION_ERROR를 반환합니다.
그 밖의 요청 오류는 오류에 정리되어 있습니다.

관련 문서

같은 페이지를 AI 개요와 함께 받는 Google AI 개요
결과 페이지를 Markdown으로 읽는 웹 스크레이프
지역과 위치