구글 서치콘솔 API로는 검색 실적 데이터(검색 애널리틱스), 사이트맵, 사이트(속성) 목록, URL 검사 결과를 프로그램으로 받아 올 수 있습니다.
Google API 콘솔에서 프로젝트를 만들고 Search Console API를 사용 설정한 뒤 OAuth2 인증을 붙이면 시작할 수 있고, 2026년 10월 26일 공식 문서 기준으로 무료지만 사용량 한도가 있습니다.
API(프로그램끼리 데이터를 주고받는 창구)는 개발자가 다루는 영역입니다. 그래서 이 글은 사장님이 개발자에게 맡길 때 알아 둘 범위와, 굳이 API까지 가지 않아도 되는 경우를 Google for Developers와 Search Console 고객센터 원문으로 정리했습니다.
1. 구글 서치콘솔 API로 무엇을 받을 수 있나요?
네 가지입니다. Search Console API 공식 문서가 꼽은 서비스는 이렇습니다.
- 검색 애널리틱스 — 사이트의 트래픽 데이터를 조회합니다
- 사이트맵 — 사이트맵 목록을 보고, 특정 사이트맵 정보를 요청하고, 사이트맵을 제출합니다
- 사이트 — Search Console 계정의 속성을 나열·추가·삭제합니다
- URL 검사 — Google 색인의 페이지 상태를 검사합니다(Search Console의 URL 검사와 같음)
공식 문서는 각 API가 Search Console 보고서의 기능을 나타낸다고 설명합니다.
결과는 JSON(프로그램이 읽기 쉬운 글자 형식)으로 돌아옵니다. 검색 애널리틱스 결과는 클릭수가 많은 순서로 정렬됩니다.
2. 시작 순서 — 계정, 프로젝트, 사용 설정, 인증
Search Console API 「기본 요건」 문서가 적은 준비 순서는 이렇습니다.
- Google 계정이 있고, 그 계정에 해당 속성의 Search Console 권한이 있어야 합니다
- Google API 콘솔에서 프로젝트를 만들고 애플리케이션을 등록합니다
- 프로젝트에서 Google Search Console API를 사용 설정합니다
- OAuth2 사용자 인증 정보를 만듭니다(Testing Tools API를 뺀 모든 Search Console API에 필요)
권한은 소유자·전체·읽기 가운데 알맞은 것이 있어야 합니다. 예를 들어 검색 실적을 조회하는 searchAnalytics.query는 그 속성의 읽기 권한이 필요합니다.
개발자에게 맡길 때는 속성 소유자가 Search Console 설정 > 사용자 및 권한에서 개발자의 Google 계정을 사용자로 추가해 권한을 줄 수 있습니다. 공식 문서 예시대로라면 검색 실적 조회에는 읽기 권한이 필요합니다.
API는 직접 HTTP로 부를 수도 있고, 공식 문서가 권하는 클라이언트 라이브러리로 부를 수도 있습니다. Python과 Java 빠른 시작 가이드가 있습니다.
3. 코드는 이 정도로 짧습니다
공식 Python 빠른 시작은 Google의 OAuth 샘플에서 몇 줄만 바꿔 씁니다. 읽기 전용 권한 범위와 서비스 이름을 이렇게 적습니다.
SCOPES = ['https://www.googleapis.com/auth/webmasters.readonly']API_SERVICE_NAME = 'searchconsole'API_VERSION = 'v1'
검색 실적 조회는 기간과 묶을 기준(측정기준)을 보냅니다. 공식 문서 예시는 시작일·종료일과 국가·기기 기준을 넣은 요청입니다.
{"startDate": "2015-04-01", "endDate": "2015-05-01", "dimensions": ["country","device"]}
조회 기간은 1일 이상이어야 하고, 날짜로 묶으면 데이터가 없는 날은 결과에서 빠집니다. 실적 보고서에서도 검색어·국가·기기·날짜 같은 측정기준으로 묶어 볼 수 있습니다.
4. 무료지만 사용량 한도가 있습니다
요금은 들지 않습니다. 「가격 책정」 문서 원문은 이렇습니다. Google Search Console API는 모두 무료로 사용할 수 있습니다. 하지만 사용량 한도가 적용됩니다.
「사용 제한」 문서에 적힌 한도는 다음과 같습니다. QPM은 분당 요청 수, QPD는 하루 요청 수, QPS는 초당 요청 수입니다. 2026년 10월 26일 공식 문서 기준이며 바뀔 수 있습니다.
- 검색 애널리틱스 — 사이트당 1,200 QPM, 사용자당 1,200 QPM, 프로젝트당 30,000,000 QPD · 40,000 QPM
- URL 검사 — 사이트당 2000 QPD · 600 QPM, 프로젝트당 10,000,000 QPD · 15,000 QPM
- 그 밖의 기능 — 사용자당 20 QPS · 200 QPM, 프로젝트당 100,000,000 QPD
사이트 하나 기준으로 보면 URL 검사는 하루 2000번(2000 QPD)까지 페이지 상태를 검사할 수 있다는 뜻입니다. 그 밖의 기능에는 사이트맵·사이트 목록 같은 요청이 들어갑니다.
5. 「할당량 초과」가 뜨면 이렇게 줄입니다
검색 애널리틱스에는 요청 횟수 한도 말고도 「로드」(요청 하나가 쓰는 내부 자원) 한도가 있습니다. 대부분의 사용자는 넘지 않지만, 넘으면 '할당량 초과' 오류가 뜹니다.
- 단기 한도(10분 단위)를 넘었다면 15분 정도 기다린 뒤 다시 시도하고, 요청을 하루에 걸쳐 흩어 놓습니다
- 페이지와 검색어를 함께 묶거나 거르는 요청이 가장 무겁습니다. 둘 중 하나를 빼면 가벼워집니다
- 기간이 길수록 무겁습니다. 6개월 범위 요청은 1일 범위 요청보다 훨씬 무겁습니다
- 지난달 데이터처럼 같은 데이터를 반복해서 다시 조회하지 않습니다
현재 사용량은 Google API 콘솔의 프로젝트 할당량 탭에서 볼 수 있습니다. 한도를 늘리려면 API 콘솔에서 요청하며, 프로젝트에 결제 계정이 없으면 먼저 만들라고 공식 문서는 안내합니다.
6. API까지 가지 않아도 되는 경우
숫자를 엑셀로 보는 정도라면 API가 필요 없습니다. 고객센터는 많은 보고서에서 내보내기 버튼으로 차트와 표 데이터를 모두 내려받을 수 있다고 안내합니다. 표에 ~ 나 - 로 보이는 값은 내려받은 파일에서 0으로 나옵니다.
매주 실적 보고서를 내보내 보는 사장님이라면 API 없이 Search Console 화면만으로 충분합니다. 공식 문서도 Search Console을 써 본 적이 없다면 코딩 전에 화면부터 써 보라고 권합니다.
반대로 데이터가 아주 많은 큰 사이트를 위해서는 BigQuery(Google의 데이터 분석 서비스)로 실적 데이터를 매일 내보내는 기능이 따로 있습니다. 고객센터는 이 기능이 일일 API 행 제한(50,000개)을 넘는 대규모 사이트에 유용하다고 적었습니다.
다만 BigQuery 내보내기는 Google Cloud Platform, BigQuery, SQL을 잘 알아야 쓸 수 있다고 고객센터가 밝혔습니다. 이 역시 개발자와 함께 정할 일입니다.
정리하면 서치콘솔 API는 이렇게 판단합니다.
- 받을 수 있는 것은 검색 애널리틱스·사이트맵·사이트·URL 검사 네 가지입니다
- Google API 콘솔 프로젝트, API 사용 설정, OAuth2 인증이 필요합니다
- 무료지만 사용량 한도가 있고, 한도는 바뀔 수 있습니다
- 개발자에게는 속성 소유자가 사용자 및 권한에서 권한을 줍니다
- 보고서를 가끔 보는 정도면 화면의 내보내기 버튼으로 충분합니다
화면에서 무엇을 먼저 보는지는 구글 서치콘솔 사용법 총정리에, 보고서에 뜨는 메시지의 뜻은 구글 서치콘솔 오류, 자주 뜨는 메시지 정리에 있습니다.
페이지 하나를 손으로 알리는 법은 구글 서치콘솔 색인 생성 요청하는 법을 보세요.
참고자료 (모두 2026년 10월 26일 확인)
- Google for Developers 「Search Console API」 개요·메서드 목록 — developers.google.com/webmaster-tools/v1/api_reference_index
- Google for Developers 「Search Console API 기본 요건」 — developers.google.com/webmaster-tools/v1/prereqs
- Google for Developers 「Search Console API 사용 제한」 — developers.google.com/webmaster-tools/limits
- Google for Developers 「Search Console API 가격 책정」 — developers.google.com/webmaster-tools/pricing
- Search Console 고객센터 「사용자, 소유자, 권한 관리」 — support.google.com/webmasters/answer/7687615
- Google for Developers 「빠른 시작: Python에서 Search Console 앱 실행」 — developers.google.com/webmaster-tools/v1/quickstart/quickstart-python
- Search Console 고객센터 「실적 보고서(Google 검색 결과): 개요 및 기본 설정」 — support.google.com/webmasters/answer/7576553
- Search Console 고객센터 「BigQuery로 Search Console 데이터 내보내기」 — support.google.com/webmasters/topic/12917674
#구글서치콘솔 #서치콘솔API #SearchConsoleAPI #검색데이터 #구글검색실적
