측정·순위 · 공식 문서
구글 서치 콘솔 API, 실적 데이터 받는 순서와 사용 한도
Search Console API 의 searchAnalytics.query 로 실적 보고서 데이터를, urlInspection.index.inspect 로 URL 검사 결과를 받습니다. 그 속성에 권한이 있는 구글 계정과 OAuth 2.0 인증이 필요하고, 한 번에 최대 25,000행씩 나눠 받습니다.
서치 콘솔 화면의 표를 매주 손으로 내려받아 붙이기는 번거롭습니다. Search Console API 를 쓰면 실적 보고서와 같은 데이터를 사내 보고서나 데이터 창고로 바로 받습니다.
구글 개발자 문서의 개요, 인증, Search Analytics 안내, 사용 한도를 원문으로 옮겼습니다. 받은 숫자의 뜻은 「SEO 성과, 클릭·노출·게재순위 집계 방식」 편에 자세히 적었습니다.
발견 01
API 는 서비스 4개로 나뉘고, 서비스마다 서치 콘솔 화면 하나에 대응합니다
| 서비스 | 메서드 | 대응하는 화면 | 공식 문서 원문 |
|---|---|---|---|
| Search Analytics | query | 실적 보고서 | Search Analytics - Query traffic data for your site.Search Analytics: 사이트의 검색 트래픽 데이터를 조회한다. |
| Sitemaps | delete, get, list, submit | 사이트맵 보고서 | Sitemaps - List all your sitemaps, request information about a specific sitemap, and submit a sitemap to Google.Sitemaps: 사이트맵 목록을 보고, 특정 사이트맵 정보를 받고, 구글에 사이트맵을 제출한다. |
| Sites | add, delete, get, list | 속성 목록 | Sites - List/add/remove properties from your Search Console account.Sites: 서치 콘솔 계정의 속성을 나열하고 추가하고 삭제한다. |
| URL Inspection | index.inspect | URL 검사 도구 | URL Inspection - Inspect the status of a page in the Google index (equivalent to URL Inspection in Search Console).URL Inspection: 구글 색인 속 페이지 상태를 검사한다(서치 콘솔의 URL 검사와 같다). |
Each API represents the functionality of a report in Search Console.
API 하나하나가 서치 콘솔 보고서 하나의 기능에 해당한다.
발견 02
인증은 OAuth 2.0 하나뿐이고, 보고서용이면 읽기 권한으로 충분합니다
| 조건 | 공식 문서 원문 |
|---|---|
| 서치 콘솔 권한 | You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.API 로 접근하려는 서치 콘솔 속성에 알맞은 권한(소유자·전체·읽기)이 있어야 한다. |
| 실적 조회에 필요한 권한 | For example, in order to run searchAnalytics.query you need read permissions on that property.예를 들어 searchAnalytics.query 를 실행하려면 그 속성의 읽기 권한이 있어야 한다. |
| 인증 방식 | Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported.요청 인증은 OAuth 2.0 으로 해야 한다. 다른 인증 방식은 지원하지 않는다. |
| 인증 정보 | All Search Console APIs except the Testing Tools API require OAuth2 credentials.Testing Tools API 를 뺀 모든 서치 콘솔 API 는 OAuth2 인증 정보가 필요하다. |
| 범위 webmasters | Read/write access.읽기·쓰기 권한. |
| 범위 webmasters.readonly | Read-only access.읽기 전용 권한. |
발견 03
실적 데이터는 날짜부터 확인하고, 25,000행씩 나눠 받습니다
| 받는 법 | 공식 문서 원문 |
|---|---|
| 받을 수 있는 범위 | The query() method exposes all the data available in the Performance report in Search Console.query() 메서드는 서치 콘솔 실적 보고서에 있는 데이터를 모두 내보낸다. |
| 기간 | You must define a date range of one or more days.하루 이상의 기간을 정해야 한다. |
| 먼저 날짜 확인 | Before running a query, you should first test for the presence of data in that time range.조회를 실행하기 전에 그 기간에 데이터가 있는지 먼저 시험한다. |
| 나눠 받기 | If your query has more than 25,000 rows of data, you can request data in batches of 25,000 rows at a time by sending multiple queries and incrementing the startRow value each time.쿼리 결과가 25,000행을 넘으면 startRow 값을 늘려 가며 여러 번 요청해 25,000행씩 나눠 받는다. |
| 끝을 아는 법 | Count the number of retrieved rows; if you get less than the number of rows requested, you have retrieved all the data.받은 행 수를 센다. 요청한 행 수보다 적으면 데이터를 다 받은 것이다. |
| 날짜 기준 | [Required] Start date of the requested date range, in YYYY-MM-DD format, in PT time (UTC - 7:00/8:00).시작일은 YYYY-MM-DD 형식이며 미국 태평양 시간(PT) 기준이다. |
The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.
API 는 서치 콘솔 내부 한계에 묶여 있어, 모든 행이 아니라 앞쪽 행을 돌려준다.
| 최근 데이터 | 공식 문서 원문 |
|---|---|
| dataState 를 비우면 | If "final" (case-insensitive) or if this parameter is omitted, the returned data will include only finalized data.dataState 가 final 이거나 비어 있으면 확정된 데이터만 돌려준다. |
| dataState 가 all 이면 | [Optional] If "all" (case-insensitive), data will include fresh data.dataState 가 all 이면 아직 확정되지 않은 최신 데이터까지 포함한다. |
| 아직 바뀌는 구간 | All values after the first_incomplete_date may still change noticeably.first_incomplete_date 이후의 값은 아직 눈에 띄게 바뀔 수 있다. |
발견 04
사용 한도는 7줄이고, 부하를 키우는 것은 차원과 기간입니다
| 서비스 | 단위 | 한도(원문) |
|---|---|---|
| Search Analytics | 사이트당 | 1,200 QPM |
| Search Analytics | 사용자당 | 1,200 QPM |
| Search Analytics | 프로젝트당 | 30,000,000 QPD · 40,000 QPM |
| URL Inspection | 사이트당 | 2000 QPD · 600 QPM |
| URL Inspection | 프로젝트당 | 10,000,000 QPD · 15,000 QPM |
| 그 밖의 서비스 | 사용자당 | 20 QPS · 200 QPM |
| 그 밖의 서비스 | 프로젝트당 | 100,000,000 QPD |
| 부하 한도를 넘었을 때 | 공식 문서 원문 |
|---|---|
| 기다리기 | If you exceed your quota, wait 15 minutes and try again.한도를 넘으면 15분 기다린 뒤 다시 시도한다. |
| 가장 무거운 조회 | Queries grouped/filtered by page AND query string are the most expensive.페이지와 검색어로 함께 묶거나 거른 조회가 가장 무겁다. |
| 기간 | So queries with a six month range are much more expensive than a query with a one day range.6개월 기간 조회는 하루 기간 조회보다 훨씬 무겁다. |
| 다시 조회 | Avoid requerying the same data (for example, querying all data for last month over and over).같은 데이터를 반복 조회하지 않는다(예: 지난달 전체를 계속 다시 조회). |
발견 05
URL 검사 API 는 색인에 있는 버전의 상태만 돌려줍니다
| URL 검사 | 공식 문서 원문 |
|---|---|
| 돌려주는 것 | Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.지금은 구글 색인에 있는 버전의 상태만 받을 수 있다. 실제 URL 의 색인 가능 여부는 테스트할 수 없다. |
| siteUrl 형식 | Note that URL-prefix properties must include a trailing / mark. Examples: https://www.example.com/ for a URL-prefix property, or sc-domain:example.com for a Domain property.URL 접두사 속성은 끝에 / 를 붙여야 한다. 예: URL 접두사 속성은 https://www.example.com/, 도메인 속성은 sc-domain:example.com. |
예시 ① 주간 리포트를 만드는 B2B SaaS 마케팅 팀(B2B)
월요일마다 지난주 검색어별 클릭을 사내 대시보드에 붙입니다. dataState 를 비워 확정 데이터만 받고, 날짜를 PT 기준이라고 대시보드에 적어 둡니다.
query 와 page 를 함께 묶으면 가장 무거운 조회가 됩니다. 검색어 표와 페이지 표를 따로 받아 부하를 나눕니다.
예시 ② 상품 페이지 색인을 지켜보는 쇼핑몰(B2C)
매출이 큰 상품 페이지 수십 개만 골라 날마다 URL Inspection 으로 색인 상태를 받습니다. 사이트당 하루 한도 안에서 충분히 돕니다.
색인에서 빠진 URL 이 나오면 화면의 URL 검사 도구로 실제 URL 을 테스트하고 색인 생성을 요청합니다.
예시 ③ 월간 운영 보고를 내는 공공기관(B2G)
유지보수 업체가 매달 검색 유입 표를 보고서에 붙입니다. 기관 공용 계정이 업체 프로그램에 읽기 전용 범위만 허락합니다.
계약이 끝나면 기관 계정에서 그 프로그램의 접근을 거두면 됩니다. 데이터는 기관 쪽 저장소에 날짜별로 남겨 둡니다.
그럼 사내 보고서에 붙이려면 어떤 순서로 하나요?
- 서치 콘솔에서 그 속성에 읽기 이상 권한이 있는 구글 계정을 정합니다. 회사 공용 계정이 좋습니다.
- Google API Console 에서 프로젝트를 만들고 Search Console API 를 사용 설정한 뒤 OAuth 2.0 클라이언트를 등록합니다.
- 보고서만 만들 것이면 범위는 읽기 전용(webmasters.readonly)으로 요청합니다.
- Sites 의 list 로 속성 URL 을 받아 siteUrl 형식(https://www.example.com/ 또는 sc-domain:example.com)을 그대로 씁니다.
- searchAnalytics.query 를 date 차원 하나로 먼저 호출해 데이터가 있는 날짜를 확인합니다.
- query·page 차원을 붙이고 rowLimit 25000 에 startRow 를 늘려 가며 받습니다. 받은 행이 요청보다 적으면 끝입니다.
- dataState 를 비우면 확정 데이터만 옵니다. 최근 며칠이 필요하면 all 로 받고, first_incomplete_date 뒤의 값은 바뀔 수 있다고 표시합니다.
- URL Inspection 은 핵심 URL 만 골라 하루 한 번 돌립니다. 사이트당 하루 한도 안에서 정합니다.
- 받은 데이터는 날짜별로 저장해 두고, 지난 기간은 저장본에서 꺼내 씁니다.
- 받은 클릭·노출·게재순위의 뜻은 「SEO 성과, 클릭·노출·게재순위 집계 방식」 편의 원문 정리를 함께 봅니다.
조사 방법
- Google for Developers 「About the Search Console API」 (문서 수정일 2025-08-28) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/about
- Google for Developers 「API Reference」 (문서 수정일 2024-07-23) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/v1/api_reference_index
- Google for Developers 「Prerequisites」 (문서 수정일 2025-08-28) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/v1/prereqs
- Google for Developers 「Authorize Requests」 (문서 수정일 2025-08-28) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/v1/how-tos/authorizing
- Google for Developers 「Query your Google Search analytics data」 (문서 수정일 2025-08-28) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/v1/how-tos/search_analytics
- Google for Developers 「Search Analytics: query」 (문서 수정일 2026-08-11) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/v1/searchanalytics/query
- Google for Developers 「Method: index.inspect」 (문서 수정일 2024-07-23) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect
- Google for Developers 「Usage Limits」 (문서 수정일 2025-08-28) · 최종 확인일 2026-10-25 · https://developers.google.com/webmaster-tools/limits
- 서비스 4개와 메서드는 「API Reference」 표 그대로, 한도 7줄은 「Usage Limits」 목록 그대로입니다.
- 받는 순서 9단계는 위 문서들이 적은 조건과 권고를 사내 보고서 작업 순서로 묶은 것입니다. 묶는 방식은 편집 판단입니다.
- 예시 ①②③은 이해를 돕기 위해 만든 가상 상황이며, 실제 기업·기관의 사례가 아닙니다.
- 원문은 영어판(hl=en)입니다. API 서비스·메서드·필드 이름은 영어 그대로 두고, 서치 콘솔 화면 이름은 서치 콘솔 도움말 한국어판(hl=ko) 표기를 따랐습니다.