SERP API 사용 방법: Google SERP API 통합 및 API 키 설정 가이드

Google SERP API를 단계별로 설정하는 방법: API 키를 발급받아 저장하고, 첫 검색을 실행하고, 결과를 현지화하고, 오류를 처리하고, 검증된 Python으로 순위를 추적하세요.

SERP API는 검색 엔진 쿼리를 대신 실행하고 결과 페이지를 구조화된 JSON으로 반환합니다. 위치별 유기적 결과(organic results), 광고, 피처드 스니펫, 로컬 결과 등을 포함합니다. Google용 스크레이퍼를 직접 만들어 유지보수하는 대신, 요청 한 번을 보내고 필요한 필드만 읽으면 됩니다.

이 가이드는 처음부터 설정하는 과정을 단계별로 안내합니다: API 키 발급 및 보관, 첫 검색 실행, 올바른 위치와 기기에 맞는 결과 받기, 오류 처리, 결과를 순위 확인으로 전환하기까지 다룹니다. 예시로 Shifter의 SERP API를 사용하지만, 대부분의 SERP API는 동일한 방식으로 작동합니다.

1단계: API 키 발급받기

모든 요청에는 API 키가 필요합니다. Shifter 패널에서 SERP API를 연 다음 API Keys로 들어가 활성화된 키를 복사하세요.

키는 비밀번호처럼 취급해야 합니다:

코드와 저장소에서 분리하세요. 환경 변수나 시크릿 매니저에 저장합니다.
개발용과 운영용 키를 분리해서 사용하세요. 그래야 유출된 테스트 키가 운영 환경에 영향을 주지 않습니다.
노출 가능성이 있으면 키를 교체하고, 사용되는 모든 곳에서 업데이트하세요.

export SHIFTER_SERP_KEY="your-key-here"

2단계: 첫 검색 실행하기

API는 https://serp.shifter.io/v1 하나의 엔드포인트로 되어 있습니다. engine으로 검색 엔진을 선택하고 q로 쿼리를 전달합니다:

curl "https://serp.shifter.io/v1?engine=google&api_key=$SHIFTER_SERP_KEY&q=residential+proxies"

응답은 JSON입니다. Google 검색의 경우 organic_results에 일반 결과가 담기며, 각 결과에는 position, title, link, displayed_link, snippet이 포함됩니다. 광고나 로컬 결과 같은 다른 섹션은 결과 페이지에 해당 항목이 있을 때 나타납니다.

같은 엔드포인트로 다른 검색 엔진과 Google의 여러 영역도 다룰 수 있습니다: engine을 bing이나 yandex로 바꾸면 해당 검색 엔진 결과를, google_maps, google_news, google_shopping으로 바꾸면 다른 Google 결과를 받을 수 있습니다. 이 가이드의 나머지 내용은 모든 경우에 동일하게 적용되며, 응답의 필드만 달라집니다.

3단계: 올바른 위치와 기기에 맞는 결과 받기

검색 결과는 위치, 언어, 기기에 따라 크게 달라지는 경우가 많습니다. 이 요소들을 고정하지 않은 순위 확인은 매번 다른 결과 페이지를 측정하는 셈입니다.

매개변수	설정 내용	예시
`location`	검색이 이루어지는 위치	`Austin,Texas,United States`
`gl`	결과의 국가	`us`
`hl`	인터페이스 언어	`en`
`device`	데스크톱, 모바일, 태블릿 결과	`mobile`

위치는 도시, 지역, 국가를 모두 포함해 명확히 기재하세요. “Springfield” 같은 짧은 이름은 모호할 수 있습니다. 로컬 SEO를 위한 지역 타겟 SERP API 가이드에서 위치 정확도가 왜 중요한지 설명합니다.

4단계: 오류 처리하기

요청은 지나가는 이유와 지나가지 않는 이유로 실패할 수 있습니다:

재시도는 속도 제한과 일시적인 서버 오류에 적용하며, 매번 대기 시간을 늘립니다.
중단하고 수정해야 하는 경우는 인증 오류와 잘못된 요청 오류입니다. 재시도해도 같은 실패만 반복됩니다.
모든 요청에 타임아웃을 설정해, 느린 검색 하나가 전체 실행을 막지 않도록 합니다.

종합하기

아래 헬퍼 함수는 환경 변수에서 키를 읽고, 위치/언어/기기를 항상 함께 전송하며, 재시도할 가치가 있는 오류만 재시도하고, 유기적 결과에서 특정 도메인의 순위를 찾는 함수를 포함합니다:

import os
import time
from urllib.parse import urlparse

import requests

API = "https://serp.shifter.io/v1"
RETRY = {408, 429, 500, 502, 503}


def google_search(query, location, gl="us", hl="en", device="desktop", session=None, attempts=3):
    """One Google search as seen from `location`, returned as parsed JSON."""
    session = session or requests.Session()
    params = {"engine": "google", "api_key": os.environ["SHIFTER_SERP_KEY"], "q": query,
              "location": location, "gl": gl, "hl": hl, "device": device}
    for attempt in range(1, attempts + 1):
        response = session.get(API, params=params, timeout=60)
        if response.status_code == 200:
            return response.json()
        if response.status_code not in RETRY or attempt == attempts:
            raise RuntimeError(f"{query!r}: HTTP {response.status_code} {response.text[:200]}")
        time.sleep(2 * attempt)


def rank_of(serp, domain):
    """Position of the first organic result on `domain`, or None if it is not there."""
    for result in serp.get("organic_results", []):
        host = urlparse(result["link"]).netloc.lower()
        if host == domain or host.endswith("." + domain):
            return result["position"]
    return None

오스틴에서 모바일로 두 키워드에 대한 사이트 순위를 확인하는 예시:

from serp import google_search, rank_of

keywords = ["emergency plumber", "water heater repair"]
for keyword in keywords:
    serp = google_search(keyword, location="Austin,Texas,United States", device="mobile")
    print(keyword, rank_of(serp, "example-plumbing.com"))

이 헬퍼 함수의 요청 매개변수, 재시도, 오류 처리, 순위 조회 기능을 시뮬레이션된 응답으로 테스트했습니다.

5단계: 순위 추적으로 전환하기

검색 한 번은 하나의 스냅샷일 뿐입니다. 추적이란 동일한 검색을 일정에 따라 반복 실행하고 결과를 저장하는 것을 의미합니다:

키워드 목록을 고정하고, 각 키워드마다 위치, 언어, 기기도 고정합니다.
일정에 따라 실행합니다. 시장에서 순위가 얼마나 자주 움직이는지에 따라 매일 또는 매주 실행합니다.
순위만이 아니라 전체 응답을 시간 및 설정과 함께 저장해, 나중에 무엇이 변했는지 되짚어볼 수 있게 합니다.
중요한 변화에 대해 알림을 설정합니다: 상위 3위권 밖으로 하락, 경쟁사가 상위에 노출, 피처드 스니펫 손실 등입니다.

일일 키워드 순위 모니터링 자동화 가이드에서 일정 설정과 저장 방식을 더 자세히 다룹니다. 순위 추적이 업무의 핵심 부분이라면 SEO 모니터링 페이지에서 더 폭넓은 설정 방법을 확인할 수 있습니다.

자주 발생하는 설정 실수

위치를 설정하지 않음. 그러면 결과는 아마도 여러분의 시장과 무관한 기본 위치에서 나옵니다.
실행마다 데스크톱과 모바일을 혼용하면, 실제 변화 없이도 순위가 요동치는 것처럼 보입니다.
정확한 URL로 매칭하는 대신 도메인으로 매칭해야 합니다. 그렇지 않으면 경로가 바뀐 순위 페이지가 순위를 잃은 것처럼 보입니다.
순위만 저장. 전체 응답이 없으면 순위가 왜 바뀌었는지 알 수 없습니다.
키를 하드코딩하면 결국 언젠가 저장소에 남게 됩니다.

자주 묻는 질문

SERP API란 무엇인가요?

검색 엔진 쿼리를 대신 실행하고 결과 페이지를 구조화된 데이터로 반환하는 서비스입니다. 위치가 포함된 유기적 결과, 광고, 피처드 스니펫, 로컬 결과 등을 제공하므로 직접 검색 페이지를 스크레이핑하고 파싱할 필요가 없습니다.

SERP API 키는 어떻게 발급받나요?

SERP API 제공업체에 가입하고 대시보드에서 키를 생성합니다. Shifter 패널에서는 SERP API, 그다음 API Keys 메뉴에 키가 있습니다. 키는 코드가 아니라 환경 변수에 저장하세요.

왜 제 SERP API 결과가 Google에서 직접 보는 것과 다른가요?

보통 위치, 언어, 기기, 개인화 설정이 다르기 때문입니다. 직접 하는 검색은 개인화되어 있고 자신의 위치에서 이루어집니다. 측정하려는 시장에 맞춰 API의 위치, 언어, 기기를 명시적으로 설정하세요.

순위는 얼마나 자주 확인해야 하나요?

경쟁이 치열한 키워드와 빠르게 변하는 시장에서는 매일, 그 외 대부분의 경우에는 매주가 적절합니다. 실행마다 설정을 동일하게 유지해야 변화가 측정 방식이 아닌 실제 결과를 반영합니다.

결론

SERP API 설정은 몇 가지 단계로 이루어집니다: 키를 안전하게 저장하고, 엔진, 위치, 언어, 기기를 고정한 채 쿼리를 전송하며, 지나갈 가능성이 있는 오류만 재시도하고, 구조화된 결과에서 순위를 읽어냅니다. 동일한 검색을 일정에 따라 실행하고 전체 응답을 보관하면, 매번 같은 결과 페이지를 측정하는 순위 추적 도구를 갖추게 됩니다.