Google Search Console API는 어떻게 사용하나요?

Q: Google Search Console API는 어떻게 사용하나요?

Cloud 프로젝트를 만들고 API를 활성화한 뒤 OAuth로 인증하면 성능 데이터, URL 검사, 사이트맵을 조회할 수 있습니다. 단계별 절차와 할당량을 안내합니다.

Google Cloud 콘솔에서 프로젝트를 만들고 Google Search Console API를 활성화한 다음, OAuth 2.0 사용자 인증 정보를 생성하고 해당 속성에 접근 권한이 있는 Google 계정으로 로그인합니다. 그러면 네 가지 리소스에 요청을 보낼 수 있습니다. 클릭수, 노출수, CTR, 순위를 제공하는 Search Analytics, 색인 상태를 확인하는 URL Inspection, Sitemaps, 그리고 Sites입니다. API 키만으로는 호출할 수 없으며, 모든 호출에 OAuth 토큰이 필요합니다. 또한 할당량에 따라 한 번에 요청할 수 있는 데이터의 양이 제한됩니다.

API가 다루는 범위와 다루지 않는 범위

리소스	메서드	용도
Search Analytics	`query`	검색어, 페이지, 국가, 기기, 검색 노출 형태, 날짜 또는 시간 단위의 성능 데이터 행
URL Inspection	`index.inspect`	단일 URL의 색인된 버전: 커버리지, 마지막 크롤링, 표준 URL
Sitemaps	`list`, `get`, `submit`, `delete`	속성에 제출된 사이트맵 관리
Sites	`list`, `get`, `add`, `delete`	로그인한 계정의 속성 목록

API가 제공하는 기능은 이것이 전부입니다. 링크, 크롤링 통계, 페이지 색인 생성 보고서, 핵심 웹 바이탈 보고서는 엔드포인트가 없으므로 Search Console 인터페이스에서만 확인할 수 있습니다. URL Inspection은 Google 색인에 들어 있는 내용을 보여 줄 뿐, 페이지를 실시간으로 테스트한 결과가 아닙니다.

접근 권한 설정

Google Cloud 콘솔에서 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
해당 프로젝트에서 Google Search Console API를 활성화합니다.
OAuth 동의 화면을 구성하고 OAuth 클라이언트 ID를 만듭니다.
범위(scope)를 요청합니다. 읽기 전용은 https://www.googleapis.com/auth/webmasters.readonly, 사이트맵 제출이나 삭제까지 하려면 https://www.googleapis.com/auth/webmasters를 사용합니다.
해당 속성에 권한이 있는 계정으로 로그인합니다. 성능 데이터를 읽으려면 최소한 읽기 권한이 필요하며, API에서는 그 계정에 보이는 데이터와 동일한 범위만 볼 수 있습니다.

첫 Search Analytics 쿼리

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

사이트는 URL 인코딩하여 경로에 넣습니다. 도메인 속성은 sc-domain:example.com, URL 접두사 속성은 https://www.example.com/처럼 끝의 슬래시까지 포함한 정확한 접두사를 사용합니다. 가장 중요한 필드는 다음과 같습니다.

날짜는 시작일과 종료일을 모두 포함하며 태평양 시간(PT) 기준입니다.
type의 기본값은 web이며, 그 외에 image, video, news, googleNews, discover가 있습니다. 유형마다 별도의 요청이 필요합니다.
필터는 dimensionFilterGroups에 지정하며, equals와 contains부터 includingRegex, excludingRegex(RE2 문법)까지 연산자를 사용할 수 있습니다.
rowLimit은 1에서 25,000까지이며(기본값 1,000), 나머지 행은 startRow로 페이지를 넘겨 가져옵니다.
dataState의 기본값은 final입니다. all을 지정하면 아직 확정되지 않은 최신 날짜의 데이터가 포함되고, hourly_all은 hour 차원과 함께 사용합니다.

각 행에는 keys, clicks, impressions, ctr(0~1), position이 반환되며, 날짜별로 그룹화하지 않는 한 클릭수 기준으로 정렬됩니다.

코드 설계에 영향을 주는 제한 사항

검색 유형별로 하루 50,000행. startRow를 25,000 단위로 늘리며 페이지를 넘기고, 빈 응답이 오면 중단합니다. 최대한 많은 데이터를 가져오려면 하루 단위로 쿼리하세요.
부하 할당량. 페이지와 검색어를 함께 기준으로 그룹화하거나 필터링하는 요청이 가장 많은 비용이 들며, 날짜 범위가 길수록 짧을 때보다 비용이 커집니다. 단기 할당량을 초과하면 Google에서 15분 동안 기다리라고 안내합니다.
요청 속도. 사이트별, 사용자별로 분당 1,200건, 프로젝트별로 분당 40,000건과 하루 30,000,000건입니다.
URL Inspection 할당량. 속성당 하루 2,000건, 분당 600건입니다.
16개월 분량의 기록. 데이터는 보통 해당 날짜가 끝난 뒤 2~3일 후에 조회할 수 있습니다.
행의 합계가 전체 수치와 일치하지 않습니다. 드물게 검색되는 검색어는 검색어 단위 행에서 제외되고, 페이지 기준 그룹화는 속성 기준 그룹화와 노출수를 다르게 집계합니다. 따라서 전체 수치는 query 차원을 포함하지 않은 요청에서 읽으세요.

자주 하는 실수

속성이 https://인데 http://를 사용하거나 끝의 슬래시를 빠뜨리면, 계정에 접근 권한이 있어도 권한 오류가 발생합니다.
URL Inspection에서 속성 밖의 URL을 요청하면 거부됩니다. URL은 전달한 siteUrl 하위에 있어야 합니다.
한 달 치 데이터를 검색어와 페이지로 그룹화해 한 번에 호출하면 상위 행만 반환됩니다. 일 단위로 요청하면 더 많은 행을 받을 수 있습니다.

AutoPSEO가 도와드리는 방법

OAuth와 페이지네이션을 직접 관리하고 싶지 않다면, AutoPSEO를 사용해 보세요. AutoPSEO는 Google 로그인으로 연결되며, 동일한 데이터를 /v1의 자체 REST API(OpenAPI 3.1 문서 제공)와 MCP 서버로 제공합니다. 인증은 Account → API keys에서 발급한 API 키로 처리합니다. 읽기 전용 키도 사용할 수 있고, 검색 분석 엔드포인트는 호출당 최대 5,000행을 반환하며, 앱의 URL Inspection 도구는 Google의 하루 2,000건 할당량을 대신 계산해 줍니다. 자세한 내용은 MCP and API keys를 참고하세요. 별도의 파이프라인을 만들지 않고 16개월이 지난 데이터를 보관하는 방법은 Search Console 데이터 보관 기간을 확인하세요.

출처: Google의 API 레퍼런스, Search Analytics query 메서드, 사용 한도, 전체 데이터 가져오기, 인증 가이드.