Community연구 & 데이터 분석github.com

google-search-console-api

Google Search Console API(searchconsole v1 / webmasters v3)를 활용하여 검색 분석(Search Analytics), URL 검사, 사이트맵 및 사이트 정보를 쿼터 제한 내에서 안전하게 처리합니다. 'Search Console 데이터를 가져와', 'GSC 성능 데이터를 내보내', '페이지/쿼리별 클릭, 노출, CTR, 위치를 조회', 'GSC 파이프라인 또는 대시보드를 구축', '1,000개/25,000개 이상의 행을 가져와', 'URL 검사/인덱스 상태 확인', '대량 URL 검사', '사이트맵 제출', 'Search Console 속성 나열', OAuth 또는 서비스 계정 설정, '쿼터 초과', 403 또는 '사용자에게 충분한 권한이 없습니다' 오류를 디버깅할 때 사용하십시오.

google-search-console-api란 무엇인가요?

이 스킬은 Google Search Console API(searchconsole v1 / webmasters v3)를 사용하는 개발자 및 SEO 전문가를 위한 완벽한 가이드입니다. 성능 보고서(검색 분석), URL 검사, 사이트맵 및 사이트 관리 등 GSC의 핵심 기능을 프로그래밍 방식으로 활용할 수 있도록 지원합니다. 가장 중요한 점은 **완전하고 정확한 데이터를 쿼터 제한을 초과하지 않고 안전하게 추출하는 방법**에 중점을 둡니다. Claude Code, Cursor, Codex 등 모든 AI 에이전트 플랫폼에서 사용할 수 있습니다. 이 스킬은 검색 분석 쿼리 최적화(일 단위 분할, 페이지네이션, 재집계 방지), URL 검사 예산 관리(일일 2,000건), 사이트맵 제출/삭제, OAuth 2.0 및 서비스 계정 설정, 쿼터 초과 및 권한 오류 디버깅 방법 등을 상세히 설명합니다. 실제 운영 환경에서 발생하는 'quotaExceeded', 403, 429 오류에 대한 구체적인 대처법과 함께, Python, Node.js 등 주요 언어별 클라이언트 라이브러리 사용법도 포함되어 있어, 안정적인 GSC 데이터 파이프라인 구축에 필수적인 지식을 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more 연구 & 데이터 분석 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Google Search Console API

Search Console API는 Google Search Console의 대부분 기능(성능 보고서(검색 분석), URL 검사, 사이트맵, 속성 목록(사이트))에 프로그래밍 방식으로 접근할 수 있게 해줍니다. REST/JSON API이며, 모든 호출에는 OAuth 2.0과 속성에 대한 Search Console 권한이 있는 사용자(또는 서비스 계정)가 필요합니다.

어려운 부분은 호출 자체가 아닙니다. 쿼터를 초과하지 않으면서 완전하고 정확한 데이터를 얻는 것입니다. 이 스킬의 대부분은 이 주제에 관한 것입니다.

이 스킬을 사용해야 하는 경우

  • 분석, 대시보드, 데이터 웨어하우징 또는 SEO 조사를 위해 성능 데이터(클릭, 노출, CTR, 위치)를 추출할 때
  • 대규모 URL의 색인 상태, 표준 URL 선택, robots/noindex 상태, 리치 결과 유효성을 확인할 때
  • 속성 및 권한 나열, 사이트맵 나열 또는 제출할 때
  • 예약된 동기화 작업을 설계하거나 quotaExceeded 오류가 발생하거나 행이 누락되거나 UI와 일치하지 않는 숫자가 반환되는 작업을 수정할 때

이 API에서 다루지 않는 항목: 페이지 색인(커버리지) 보고서, 링크, Core Web Vitals, 크롤링 통계, 수동 조치, 삭제 및 '색인 생성 요청' 버튼입니다. Core Web Vitals 현장 데이터는 CrUX API를 사용하고, 대규모 사이트의 대량 원시 성능 데이터는 Search Console BigQuery로의 대량 데이터 내보내기를 사용하십시오. 별도의 Indexing API는 JobPosting/BroadcastEvent 페이지만 지원합니다.

네 가지 서비스

서비스메서드HTTP범위 (최소)
검색 분석searchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
URL 검사urlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
사이트맵list / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
사이트맵submit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
사이트list / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
사이트add / deletePUT / DELETE /webmasters/v3/sites/{siteUrl}webmasters

루트 URL: https://searchconsole.googleapis.com/ (현재 디스커버리 문서, 서비스 searchconsole v1). 이전 https://www.googleapis.com/webmasters/v3/... 경로는 여전히 Google 문서 전체에 나타나며 webmasters/v3 리소스에서 계속 작동합니다.

범위: https://www.googleapis.com/auth/webmasters.readonly (읽기 전용) 및 https://www.googleapis.com/auth/webmasters (읽기/쓰기). 작업이 실제로 사이트맵을 제출/삭제하거나 사이트를 추가/제거하지 않는 한 읽기 전용을 요청하십시오.

속성 식별자 (siteUrl) — 403/404 오류의 주요 원인

  • 도메인 속성: sc-domain:example.com
  • URL 접두사 속성: https://www.example.com/ — 스키마, 호스트 및 후행 슬래시가 Search Console에 있는 것과 정확히 일치해야 합니다.
  • 경로에서 siteUrl 및 feedpath는 완전히 URL 인코딩되어야 합니다 (https%3A%2F%2Fwww.example.com%2F, sc-domain%3Aexample.com). 클라이언트 라이브러리가 자동으로 처리하지만, 원시 HTTP는 그렇지 않습니다.
  • 항상 sites.list를 호출하여 시작하고 반환된 siteUrl을 정확히 그대로 사용하십시오. siteUnverifiedUser는 데이터를 읽을 수 없습니다.

쿼터 — 루프를 작성하기 전에 읽으십시오

전체 세부 정보 및 예산 책정 워크시트: references/LIMITS.md.

검색 분석

  • QPM 한도: 사이트당 1,200 QPM, 사용자당 1,200 QPM, 프로젝트당 40,000 QPM 및 30,000,000 QPD. 예: 한 사용자가 3개 사이트를 적중하면 결합하여 1,200 QPM; 두 사용자가 한 사이트에서 1,200 QPM을 공유합니다.
  • 부하 쿼터(실제로 영향을 미치는 것): 쿼리의 내부 비용으로, 10분(단기) 및 1일(장기) 창에서 추적됩니다. 비용은 다음에 따라 증가합니다:
    • page 또는 query로 그룹화/필터링 (둘 다 함께 사용하면 가장 비쌈),
    • 날짜 범위의 길이 (6개월 ≫ 1일),
    • 이미 보유한 데이터를 다시 쿼리.
  • 이 중 하나라도 초과하면 동일한 quotaExceeded 오류가 반환됩니다. 단기: 15분 기다렸다가 재시도하십시오. 10분 창의 단일 쿼리가 여전히 실패하면 장기(일일) 부하 쿼터를 초과한 것입니다 — 비용을 줄이십시오. 재시도는 내일까지 도움이 되지 않습니다.

URL 검사: 사이트당 일일 2,000 QPD 및 600 QPM; 프로젝트당 10,000,000 QPD 및 15,000 QPM. 속성당 일일 2,000건이 실제 상한선입니다 — 샘플링을 계획하고 '모든 URL 검사'를 계획하지 마십시오.

그 외 모든 것(사이트, 사이트맵): 사용자당 20 QPS 및 200 QPM; 프로젝트당 100,000,000 QPD.

일괄 처리는 쿼터를 절약하지 않습니다: n개의 호출 일괄 처리는 n개의 요청으로 계산됩니다. 일괄 처리는 HTTP 오버헤드만 절약합니다. 현재 사용량: Google Cloud 콘솔 → APIs & Services → Search Console API → 할당량.

검색 분석: 완전하고 정확한 데이터 얻기

전체 요청/응답 스키마 및 레시피: references/SEARCH-ANALYTICS.md.

권장 패턴 (Google의 '모든 데이터' 가이드에서)

  1. 먼저 최신 상태를 확인하십시오. 필터 없이, 다른 차원 없이 date로만 그룹화하여 최근 ~10일을 쿼리하십시오. 데이터가 없는 날은 단순히 없습니다. 최종 데이터는 일반적으로 2~3일 지연됩니다.
  2. 필요한 각 type에 대해 하루에 한 번, 하루씩 (startDate == endDate) 쿼리하십시오. 일일 단일일 쿼리는 일일 쿼터를 초과하지 않아야 합니다. 16개월 범위를 page+query로 그룹화하면 초과할 것입니다.
  3. 결과를 페이지네이션하십시오: rowLimit 최대 25,000(기본값 1,000), 페이지가 요청된 행보다 적거나 0행을 반환할 때까지 startRow를 25,000씩 증가시키십시오.
  4. 완료된 기록을 다시 가져오지 마십시오. 저장하고, 새 날짜만 가져오십시오 (최근 완료되지 않은 날짜는 dataState: "all"을 사용하는 경우 다시 가져올 수 있음).
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
  "startDate": "2026-11-14",
  "endDate":   "2026-11-14",
  "dimensions": ["page", "query", "country", "device"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

이해 관계자에게 설명해야 하는 하드 데이터 제한

  • API는 모든 행이 아닌 상위 행을 반환합니다: 검색 유형별로 일일 최대 50,000행(클릭수로 정렬됨), 페이지네이션에 관계없이.
  • page 및/또는 query로 그룹화/필터링하면 일부 데이터가 손실(계산을 제한하기 위해)되고 익명화된 드문 쿼리는 절대 반환되지 않습니다. 따라서 행 합계 < 속성 총계입니다. 정확한 총계를 얻으려면 page/query 차원 없이 쿼리하십시오.
  • 합계는 집계 방식에 따라 다릅니다: byProperty(속성당 중복 제거)와 byPage(표준 URL당). page로 그룹화하거나 필터링하는 경우 byProperty는 허용되지 않습니다 — auto를 사용하십시오.
  • 날짜는 UTC가 아닌 태평양 표준시(America/Los_Angeles)입니다.
  • Search Console의 성능 데이터 보존 기간은 약 16개월입니다. 더 긴 기록이 필요하면 데이터를 유지하십시오.

올바른 메트릭 계산

  • 그룹의 CTR = sum(clicks) / sum(impressions). CTR을 평균화하지 마십시오.
  • 그룹의 위치 = 노출 가중치 적용: sum(position × impressions) / sum(impressions). 위치를 평균화하지 마십시오.
  • position은 1부터 시작하는 평균 최상위 위치이며, 낮을수록 좋습니다.

주요 요청 필드 (빠른 참조)

  • dimensions: date, hour, query, page, country (ISO 3166-1 alpha-3, 결과에서 소문자, 예: usa), device (DESKTOP/MOBILE/TABLET), searchAppearance, brandedClassification.
  • type: web(기본값), image, video, news(뉴스 탭), googleNews(news.google.com + 앱), discover, webMultimodal(렌즈/서클 투 서치/이미지 업로드). searchType은 더 이상 사용되지 않는 별칭입니다.
  • dimensionFilterGroups[].filters[]: {dimension, operator, expression}; 연산자 equals(기본값, page/query의 경우 대소문자 구분), notEquals, contains, notContains, includingRegex, excludingRegex(RE2). 그룹은 AND로 결합됩니다. groupType: "and"만 지원됩니다.
  • dimensionFilterGroups[].filterLists[]: country/device에 대한 다중 값 정확히 일치 ({"dimension":"country","expressions":["usa","can"]}). 동일한 차원을 filters와 filterLists 모두에서 필터링할 수 없습니다.
  • aggregationType: auto(기본값), byPage, byProperty(discover/googleNews의 경우 불가), byNewsShowcasePanel.
  • dataState: final(기본값), all(최종이 아닌 새 데이터 포함), hourly_all(hour 차원에 필요, 약 10일간 사용 가능). 응답 metadata.firstIncompleteDate / firstIncompleteHour는 숫자가 여전히 변경될 수 있는 지점을 표시합니다.

주의사항

  • 검색 표시는 2단계: searchAppearance를 유일한 차원으로 쿼리하여 유형을 나열한 다음, searchAppearance equals <TYPE>으로 필터링하고 다른 차원을 추가하십시오 — 유형당 하나의 쿼리.
  • brandedClassification (BRANDED / NON_BRANDED): equals만 가능; 동일한 요청에서 query 필터와 결합할 수 없음; 2026-02-21부터의 데이터이며 충분한 볼륨이 있는 최상위 속성에만 해당.
  • 결과는 클릭수 내림차순으로 정렬되며, date로 그룹화된 경우(날짜 오름차순)는 예외입니다. 동점은 임의적입니다 — 중복 제거를 위해 순서에 의존하지 마십시오.
  • 범위를 벗어난 startRow는 오류 대신 200과 0행을 반환합니다. 정확히 25,000 경계의 데이터는 빈 다음 페이지를 반환합니다.
  • 데이터가 없으면 rows는 []가 아니라 없음입니다.

URL 검사

전체 스키마, 열거형 및 분류 테이블: references/URL-INSPECTION.md.

POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
  • 색인된 버전만 보고합니다. 라이브 URL을 테스트할 수 없으며, 색인을 요청할 수 없습니다.
  • inspectionUrl은 siteUrl 하위에 있어야 합니다.
  • indexStatusResult 읽기: verdict (PASS = 유효, NEUTRAL = 제외됨, FAIL = 오류), coverageState (사람이 읽을 수 있는 문자열, 예: '제출 및 색인 생성됨'), robotsTxtState, indexingState, pageFetchState, lastCrawlTime, googleCanonical vs userCanonical, crawledAs.
  • 가장 유용한 대량 신호는 googleCanonical != userCanonical (Google이 다른 표준 URL을 선택함)입니다.
  • mobileUsabilityResult는 더 이상 사용되지 않습니다. ampResult / richResultsResult는 해당되지 않으면 없습니다.
  • 예산: 일일 2,000건/속성. 샘플의 우선 순위를 지정하십시오: 클릭수 상위 페이지, 최근 변경된 템플릿, 템플릿/패턴당 하나의 URL, 새 사이트맵의 URL.

사이트 및 사이트맵

references/SITES-AND-SITEMAPS.md를 참조하십시오. sites.list → siteEntry[] {siteUrl, permissionLevel} (값: siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser). sitemaps.list → sitemap[] (필드: path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, errors, warnings, contents[].submitted). contents[].indexed는 더 이상 사용되지 않으므로 보고하지 마십시오. submit / delete는 본문이 없고 읽기/쓰기 범위가 필요합니다. 이것들은 쓰기 작업입니다. 호출하기 전에 사용자에게 확인하십시오.

인증 및 설정

단계별, 모든 언어의 라이브러리 설치 라인 포함: references/AUTH-AND-SETUP.md.

  1. Google Cloud 프로젝트를 생성/선택 → Google Search Console API를 활성화합니다.
  2. 자격 증명을 선택합니다:
    • 설치/데스크톱 OAuth 클라이언트: 로컬에서 스크립트를 실행하는 사람용; 사용자가 브라우저에서 동의하고 새로 고침 토큰을 저장합니다.
    • 서비스 계정: 무인 작업용. 그런 다음 Search Console(설정 → 사용자 및 권한)에서 속성의 사용자로 서비스 계정 이메일을 추가합니다. 제한된 권한으로 읽기에 충분합니다. 소유자/전체 권한은 쓰기에 필요합니다. 이 단계 없이 모든 호출은 403을 반환합니다.
    • API 키는 이러한 리소스에 허용되지 않습니다. OAuth 2.0만 지원되는 프로토콜입니다.
  3. 클라이언트 라이브러리(권장)를 사용하십시오 — 예: Python google-api-python-client와 build("searchconsole", "v1", credentials=creds), Node googleapis와 google.searchconsole("v1").
from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    "sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)

resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
    "startDate": "2026-11-14", "endDate": "2026-11-14",
    "dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", [])   # 비어 있으면 없음

토큰, 클라이언트 비밀 또는 서비스 계정 키를 인쇄, 기록 또는 커밋하지 마십시오.

오류 및 재시도

전체 맵: references/ERRORS.md.

증상원인조치
401 authError / expired잘못되었거나 만료된 토큰토큰 새로 고침; 범위 확인
403 insufficientPermissions / "User does not have sufficient permission for site"잘못된 siteUrl 형식 또는 주체가 속성의 사용자가 아님sites.list 호출, 정확한 siteUrl 사용; Search Console에서 서비스 계정 추가
403 accessNotConfigured프로젝트에서 API가 활성화되지 않음Search Console API 활성화
403/429 rateLimitExceeded, userRateLimitExceededQPS/QPM지터를 포함한 지수 백오프
403/429 quotaExceeded (검색 분석)부하 쿼터15분간 한 번 대기; 단일 쿼리가 여전히 실패하면 → 장기 부하: 날짜 범위를 줄이거나 page/query를 제거하고 내일 재개
400 invalidParameter / badRequest잘못된 열거형, 날짜 순서, 동일한 차원에 filters/filterLists 혼합, byProperty와 page요청 수정; 재시도하지 않음
500 / 503 backendError일시적백오프 및 재시도 (제한적)

성능

references/BATCH-AND-PERFORMANCE.md: gzip (Accept-Encoding: gzip 및 gzip을 포함하는 User-Agent), fields=를 통한 부분 응답 (예: fields=rows(keys,clicks,impressions)), HTTP 일괄 처리 (multipart/mixed, 최대 1,000개 호출, 순서에 관계없이 실행, 각 호출은 여전히 쿼터에 포함됨).

도우미 스크립트

scripts/gsc.py는 Python 3.9+ 표준 라이브러리만 사용하는 단일 파일 CLI입니다. 진행률을 stderr에 쓰고 데이터를 stdout(기본적으로 JSONL, 또는 CSV/JSON)에 씁니다. 페이지네이션을 처리하며, 오류 재시도 및 진행률 표시줄을 포함합니다. 다음 명령으로 사용하십시오:

python3 scripts/gsc.py analytics --site "sc-domain:example.com" --start 2026-01-01 --end 2026-11-14 --dimensions page query --output data.jsonl

scripts/gsc.py inspect는 URL 검사를 위한 하위 명령을 제공합니다 (--site, --urls). scripts/gsc.py --help는 모든 옵션을 나열합니다.

관련 스킬