Google Search Console API 설정하기 - 검색 데이터 프로그래밍으로 조회

블로그를 운영하다 보면 "어떤 검색어로 유입되는가", "내 포스트가 구글에서 몇 위에 노출되는가" 같은 정보가 궁금하다. Google Search Console 대시보드에서 확인할 수도 있지만, 프로그래밍 방식으로 데이터를 조회하면 더 많은 걸 할 수 있다.

자동화된 SEO 리포트를 만들거나, OpenClaw 같은 AI 봇과 대화하면서 검색 데이터를 분석하거나, 순위 변동을 실시간으로 모니터링하는 등의 작업이 가능해진다.

이 글에서는 Google Search Console API를 설정하고 사용하는 방법을 처음부터 끝까지 정리한다.

Google Search Console API란

Google Search Console API는 Google 검색에서의 사이트 성과 데이터를 프로그래밍 방식으로 조회할 수 있는 API다.

조회 가능한 데이터:

검색 쿼리 (어떤 검색어로 유입됐는지)
클릭 수, 노출 수, CTR (클릭률), 평균 순위
페이지별 검색 성과
디바이스별, 국가별 데이터
URL 색인 상태
사이트맵 정보
크롤링 통계

활용 사례:

실시간 검색 순위 모니터링
검색 유입이 많은 키워드 분석
CTR이 낮은 페이지 찾아서 개선
새 포스트 색인 상태 확인
OpenClaw와 대화하면서 SEO 분석

사전 준비

Google Cloud 계정
Google Search Console에 사이트 등록 및 소유권 확인 완료
사이트 관리자 권한

Tip: Google Analytics Data API를 먼저 설정했다면 같은 프로젝트와 서비스 계정을 재사용할 수 있다.

1단계: Google Cloud 프로젝트 및 서비스 계정

Google Analytics API를 이미 설정했다면 이 단계를 건너뛸 수 있다.

새로 시작하는 경우

https://console.cloud.google.com 접속
프로젝트 생성 (예: blog-seo-analytics)
API 및 서비스 → 사용자 인증 정보 → 서비스 계정 만들기
서비스 계정 이름: blog-search-console-reader
JSON 키 파일 다운로드

기존 GA API 프로젝트가 있는 경우

같은 프로젝트, 같은 서비스 계정을 사용하면 된다. JSON 키 파일도 동일하게 사용 가능.

2단계: Search Console API 활성화

Google Cloud Console → API 및 서비스 → 라이브러리
"Google Search Console API" 검색
Google Search Console API 선택
사용 설정 클릭

3단계: Search Console 권한 부여

서비스 계정에 Search Console 데이터를 읽을 수 있는 권한을 부여한다.

https://search.google.com/search-console 접속
사이트 속성 선택
왼쪽 메뉴 설정 클릭
사용자 및 권한 클릭
사용자 추가 클릭
서비스 계정 이메일 입력
- JSON 파일의 client_email 값
- 예: blog-search-console-reader@project.iam.gserviceaccount.com

권한 선택: 제한된 액세스 vs 전체 권한

제한된 액세스 (권장)

검색 성과 데이터 조회 ✅
URL 검사 ✅
사이트맵 조회 ✅
크롤링 통계 조회 ✅
사이트맵 제출 ❌
재크롤링 요청 ❌

전체 권한

위의 모든 것 ✅
사이트맵 제출 ✅
재크롤링 요청 ✅

보안 권장사항

데이터 조회만 한다면 "제한된 액세스"를 선택한다.

이유:

API로 할 수 있는 작업이 제한됨
혹시 키가 유출돼도 피해 최소화
사이트맵 제출이나 재크롤링은 수동으로 해도 됨

안심해도 되는 점:

사이트 삭제는 API로 불가능 (어떤 권한이든)
속성 삭제는 API로 불가능
사용자 권한 변경도 API로 불가능

OpenClaw로 데이터 분석만 한다면 "제한된 액세스"로 충분하다.

4단계: Site URL 확인

API 호출 시 필요한 Site URL을 확인한다.

Search Console에서 사용하는 속성 URL 형식:

URL 접두어 속성: https://namhoonlee.com
도메인 속성: sc-domain:namhoonlee.com

대부분 URL 접두어 형식을 사용한다.

5단계: API 테스트

Node.js로 간단한 테스트를 해보자.

패키지 설치

npm install googleapis

테스트 스크립트

test-search-console.js 파일을 만든다:

const { google } = require('googleapis');

const auth = new google.auth.GoogleAuth({
  keyFile: './your-service-account-key.json',
  scopes: ['https://www.googleapis.com/auth/webmasters.readonly'],
});

const searchconsole = google.searchconsole({ version: 'v1', auth });

const siteUrl = 'https://namhoonlee.com'; // 본인의 사이트 URL

async function getSearchData() {
  try {
    const response = await searchconsole.searchanalytics.query({
      siteUrl: siteUrl,
      requestBody: {
        startDate: '2026-02-02',
        endDate: '2026-02-08',
        dimensions: ['query'],
        rowLimit: 10,
      },
    });

    console.log('최근 7일간 검색 쿼리 Top 10:');
    console.log('');
    
    if (response.data.rows) {
      response.data.rows.forEach((row, index) => {
        console.log(`${index + 1}. ${row.keys[0]}`);
        console.log(`   클릭: ${row.clicks}, 노출: ${row.impressions}`);
        console.log(`   CTR: ${(row.ctr * 100).toFixed(2)}%, 평균 순위: ${row.position.toFixed(1)}`);
        console.log('');
      });
    } else {
      console.log('데이터가 없습니다.');
    }
  } catch (error) {
    console.error('에러 발생:', error.message);
  }
}

getSearchData();

실행

node test-search-console.js

결과:

최근 7일간 검색 쿼리 Top 10:

1. next.js 시작하기
   클릭: 45, 노출: 523
   CTR: 8.60%, 평균 순위: 3.2

2. react hooks 정리
   클릭: 38, 노출: 412
   CTR: 9.22%, 평균 순위: 2.8

3. typescript 팁
   클릭: 31, 노출: 287
   CTR: 10.80%, 평균 순위: 4.1
...

성공적으로 데이터가 조회되면 설정 완료!

실전 활용 예제

페이지별 검색 성과

async function getPagePerformance() {
  const response = await searchconsole.searchanalytics.query({
    siteUrl: siteUrl,
    requestBody: {
      startDate: '2026-01-10',
      endDate: '2026-02-08',
      dimensions: ['page'],
      rowLimit: 10,
    },
  });

  console.log('페이지별 검색 성과 Top 10:');
  response.data.rows?.forEach((row, index) => {
    console.log(`${index + 1}. ${row.keys[0]}`);
    console.log(`   클릭: ${row.clicks}, CTR: ${(row.ctr * 100).toFixed(2)}%`);
  });
}

CTR이 낮은 페이지 찾기

async function findLowCTRPages() {
  const response = await searchconsole.searchanalytics.query({
    siteUrl: siteUrl,
    requestBody: {
      startDate: '2026-01-10',
      endDate: '2026-02-08',
      dimensions: ['page'],
      rowLimit: 100,
    },
  });

  console.log('노출은 많은데 CTR이 낮은 페이지 (개선 필요):');
  const lowCTRPages = response.data.rows
    ?.filter(row => row.impressions > 100 && row.ctr < 0.05)
    .sort((a, b) => b.impressions - a.impressions)
    .slice(0, 5);

  lowCTRPages?.forEach((row, index) => {
    console.log(`${index + 1}. ${row.keys[0]}`);
    console.log(`   노출: ${row.impressions}, CTR: ${(row.ctr * 100).toFixed(2)}%`);
    console.log(`   → 제목이나 메타 설명 개선 고려`);
  });
}

디바이스별 검색 성과

async function getDeviceBreakdown() {
  const response = await searchconsole.searchanalytics.query({
    siteUrl: siteUrl,
    requestBody: {
      startDate: '2026-01-10',
      endDate: '2026-02-08',
      dimensions: ['device'],
    },
  });

  console.log('디바이스별 검색 성과:');
  response.data.rows?.forEach(row => {
    console.log(`${row.keys[0]}: ${row.clicks}클릭, ${row.impressions}노출`);
  });
}

URL 색인 상태 확인

const { google } = require('googleapis');

async function checkIndexing(url) {
  const indexing = google.indexing({ version: 'v3', auth });
  
  try {
    const response = await indexing.urlNotifications.getMetadata({
      url: url,
    });
    
    console.log(`${url} 색인 상태:`);
    console.log(response.data);
  } catch (error) {
    console.log(`${url}는 아직 색인되지 않았거나 데이터가 없습니다.`);
  }
}

checkIndexing('https://namhoonlee.com/posts/new-post');

OpenClaw와 통합

Search Console 정보를 OpenClaw에 보관하고 대화로 분석할 수 있다.

인증 정보 저장

Google Analytics와 동일한 서비스 계정 키를 사용하면 된다.

# OpenClaw 워크스페이스
cd ~/.openclaw/workspaces/main

# 이미 GA용으로 저장한 JSON 키를 재사용
# 또는 별도 저장
cp ~/Downloads/blog-search-console-*.json credentials/gsc-service-account.json

OpenClaw로 Search Console 데이터 조회

예시 대화:

사용자: "이번주에 어떤 검색어로 블로그에 많이 들어왔어?"

OpenClaw: 최근 7일간 검색 쿼리를 조회하겠습니다.

Top 5 검색어:

"next.js 시작하기" - 45클릭, 평균 3.2위

"react hooks 정리" - 38클릭, 평균 2.8위

"typescript 팁" - 31클릭, 평균 4.1위

"docker 입문" - 27클릭, 평균 5.2위

"git 커맨드" - 23클릭, 평균 6.3위

예시 대화:

사용자: "CTR 낮은 페이지 찾아줘"

OpenClaw: 노출은 많은데 CTR이 낮은 페이지를 찾았습니다.

개선이 필요한 페이지:

/posts/nextjs-guide - 노출 523회, CTR 3.2% → 제목에 "완벽 가이드" 같은 클릭 유도 키워드 추가 고려

/posts/react-hooks - 노출 412회, CTR 4.1% → 메타 설명에 구체적인 혜택 명시 권장

예시 대화:

사용자: "새로 쓴 포스트 색인됐어?"

OpenClaw: /posts/tailscale-remote-dev-setup 색인 상태를 확인하겠습니다.

✅ 색인됨 (2026-02-09)

현재 평균 순위: 12.4위

지난 3일간 노출: 87회, 클릭: 5회

자동화된 SEO 리포트

OpenClaw cron으로 주간 SEO 리포트를 자동 전송:

# 매주 월요일 오전 10시
openclaw cron add --schedule "0 10 * * 1" \
  --task "지난주 Search Console 데이터 요약해줘. 검색어 Top 10, CTR 낮은 페이지, 순위 변동 큰 페이지 위주로."

활용 시나리오

1. 키워드 전략

"어떤 키워드로 유입이 많아?"
"순위는 높은데 클릭이 적은 키워드는?"
"최근 급상승한 검색어는?"

2. 콘텐츠 최적화

"CTR 낮은 페이지 찾아서 개선 방법 제안해줘"
"노출은 많은데 순위가 낮은 페이지는?"
"모바일 vs 데스크톱 성과 차이는?"

3. 색인 모니터링

"새 포스트 5개 색인 상태 확인해줘"
"색인 안 된 페이지 있어?"
"크롤링 에러 있는지 확인해줘"

Google Analytics와 함께 사용

Search Console과 Analytics를 함께 사용하면 더 강력하다.

Search Console: "어떻게 찾아왔나"

검색어, 순위, CTR

Analytics: "찾아온 후 무엇을 했나"

페이지뷰, 체류 시간, 이탈률

조합 분석 예시:

사용자: "검색 유입은 많은데 이탈률이 높은 페이지 찾아줘"

OpenClaw:

Search Console에서 검색 클릭 많은 페이지 조회

Analytics에서 해당 페이지들의 이탈률 확인

교차 분석 결과 제시

보안 주의사항

제한된 액세스 권장

데이터 조회만 필요하면 "제한된 액세스" 권한으로 충분하다.

제한된 액세스로도 가능한 것:

모든 검색 성과 데이터 조회
URL 색인 상태 확인
크롤링 통계 조회

전체 권한이 필요한 경우:

사이트맵 자동 제출
재크롤링 자동 요청

JSON 키 파일 관리

Search Console API도 같은 서비스 계정 키를 사용하므로, GA API와 동일한 보안 수칙을 따른다.

Git에 커밋하지 않기
환경 변수로 관리
정기적으로 키 갱신

할당량 및 제한사항

API 할당량 (일일):

Search Analytics 쿼리: 1,200 요청
URL 검사: 2,000 요청

일반적인 블로그 자동화 용도로는 충분하다.

데이터 지연:

검색 성과 데이터는 2-3일 지연될 수 있음
실시간 데이터가 아님

트러블슈팅

"User does not have sufficient permissions"

Search Console에서 서비스 계정 이메일에 권한을 부여했는지 확인한다. "제한된 액세스" 이상의 권한 필요.

"Site not found"

siteUrl이 정확한지 확인한다. Search Console에 등록된 URL과 정확히 일치해야 한다.

// 올바른 형식
siteUrl: 'https://namhoonlee.com'

// 틀린 형식
siteUrl: 'namhoonlee.com' // https:// 누락
siteUrl: 'https://namhoonlee.com/' // 끝의 / 주의

데이터가 없음

사이트가 너무 최근에 등록됐거나
검색 트래픽이 아직 없거나
날짜 범위를 너무 최근으로 설정한 경우

2-3일 전 데이터로 테스트해본다.

정리

Google Search Console API를 설정하면 블로그의 검색 성과를 데이터 기반으로 분석할 수 있다.

설정 단계 요약:

Google Cloud 프로젝트 및 서비스 계정 (GA와 공유 가능)
Search Console API 활성화
Search Console 권한 부여 (제한된 액세스 권장)
Site URL 확인
API 테스트

OpenClaw 통합:

대화로 검색 데이터 분석
자동화된 SEO 리포트
Analytics와 교차 분석

Search Console API를 활용하면 어떤 키워드가 효과적인지, 어떤 페이지를 개선해야 하는지 명확히 알 수 있다. SEO를 감이 아니라 데이터로 할 수 있게 되는 셈이다.

Google Search Console API란

사전 준비

1단계: Google Cloud 프로젝트 및 서비스 계정

새로 시작하는 경우

기존 GA API 프로젝트가 있는 경우

2단계: Search Console API 활성화

3단계: Search Console 권한 부여

권한 선택: 제한된 액세스 vs 전체 권한

보안 권장사항

4단계: Site URL 확인

5단계: API 테스트

패키지 설치

테스트 스크립트

실행

실전 활용 예제

페이지별 검색 성과

CTR이 낮은 페이지 찾기

디바이스별 검색 성과

URL 색인 상태 확인

OpenClaw와 통합

인증 정보 저장

OpenClaw로 Search Console 데이터 조회

자동화된 SEO 리포트

활용 시나리오

Google Analytics와 함께 사용

보안 주의사항

제한된 액세스 권장

JSON 키 파일 관리

할당량 및 제한사항

트러블슈팅

"User does not have sufficient permissions"

"Site not found"

데이터가 없음

정리

참고