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.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| URL 검사 | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| 사이트맵 | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| 사이트맵 | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| 사이트 | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| 사이트 | add / delete | PUT / 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의 '모든 데이터' 가이드에서)
- 먼저 최신 상태를 확인하십시오. 필터 없이, 다른 차원 없이
date로만 그룹화하여 최근 ~10일을 쿼리하십시오. 데이터가 없는 날은 단순히 없습니다. 최종 데이터는 일반적으로 2~3일 지연됩니다. - 필요한 각
type에 대해 하루에 한 번, 하루씩 (startDate == endDate) 쿼리하십시오. 일일 단일일 쿼리는 일일 쿼터를 초과하지 않아야 합니다. 16개월 범위를 page+query로 그룹화하면 초과할 것입니다. - 결과를 페이지네이션하십시오:
rowLimit최대 25,000(기본값 1,000), 페이지가 요청된 행보다 적거나 0행을 반환할 때까지startRow를 25,000씩 증가시키십시오. - 완료된 기록을 다시 가져오지 마십시오. 저장하고, 새 날짜만 가져오십시오 (최근 완료되지 않은 날짜는
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,googleCanonicalvsuserCanonical,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.
- Google Cloud 프로젝트를 생성/선택 → Google Search Console API를 활성화합니다.
- 자격 증명을 선택합니다:
- 설치/데스크톱 OAuth 클라이언트: 로컬에서 스크립트를 실행하는 사람용; 사용자가 브라우저에서 동의하고 새로 고침 토큰을 저장합니다.
- 서비스 계정: 무인 작업용. 그런 다음 Search Console(설정 → 사용자 및 권한)에서 속성의 사용자로 서비스 계정 이메일을 추가합니다. 제한된 권한으로 읽기에 충분합니다. 소유자/전체 권한은 쓰기에 필요합니다. 이 단계 없이 모든 호출은 403을 반환합니다.
- API 키는 이러한 리소스에 허용되지 않습니다. OAuth 2.0만 지원되는 프로토콜입니다.
- 클라이언트 라이브러리(권장)를 사용하십시오 — 예: Python
google-api-python-client와build("searchconsole", "v1", credentials=creds), Nodegoogleapis와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, userRateLimitExceeded | QPS/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는 모든 옵션을 나열합니다.