Blog Google: Google API 데이터로 블로그 성능 분석하기
Google의 SEO API에 직접 접근하여 블로그 성능을 분석합니다. 실시간 Chrome 사용자 메트릭, 색인 상태, 검색 성능, 엔티티 분석, YouTube 동영상 검색, 키워드 볼륨, PDF/HTML 성능 리포트를 제공합니다.
모든 API는 정상 사용 수준에서 무료입니다. Google Cloud 프로젝트와 API 키 및/또는 서비스 계정 설정이 필요합니다.
사전 요구 사항
명령어를 실행하기 전에 항상 자격 증명을 확인하세요:
python3 skills/blog-google/scripts/run.py google_auth --check --json
설정 파일: ~/.config/claude-seo/google-api.json (claude-seo와 공유)
{
"api_key": "AIzaSy...",
"oauth_client_path": "/path/to/client_secret.json",
"default_property": "sc-domain:example.com",
"ga4_property_id": "properties/123456789",
"ads_developer_token": "...",
"ads_customer_id": "123-456-7890"
}
파일이 없으면 references/auth-setup.md를 읽고 사용자에게 설정 방법을 안내하세요.
자격 증명 등급
| 등급 | 감지 조건 | 사용 가능한 명령어 |
|---|---|---|
| 0 (API 키) | api_key 존재 | pagespeed, crux, crux-history, youtube, nlp |
| 1 (OAuth/SA) | + OAuth 토큰 또는 서비스 계정 | 등급 0 + gsc, inspect, index |
| 2 (전체) | + ga4_property_id 설정 | 등급 1 + ga4 |
| 3 (광고) | + ads_developer_token + ads_customer_id | 등급 2 + keywords |
명령어를 실행하기 전에 항상 감지된 등급을 알려주세요.
빠른 참조
| 명령어 | 설명 | 등급 |
|---|---|---|
/blog google setup | API 자격 증명 확인/설정 | -- |
/blog google pagespeed <url> | PSI Lighthouse + CrUX 필드 데이터 | 0 |
/blog google crux <url> | CrUX 필드 데이터만 (p75 메트릭) | 0 |
/blog google crux-history <url> | 25주 CWV 추세 분석 | 0 |
/blog google youtube <query> | YouTube 동영상 검색 (조회수, 좋아요, 길이) | 0 |
/blog google nlp <url-or-text> | NLP 엔티티 추출 + 감정 분석 | 0 |
/blog google gsc <property> | Search Console: 클릭수, 노출수, CTR, 순위 | 1 |
/blog google inspect <url> | URL 검사: 색인 상태, 표준 URL | 1 |
/blog google index <url> | URL을 Indexing API에 제출 | 1 |
/blog google ga4 [property-id] | GA4 유기적 트래픽 리포트 | 2 |
/blog google keywords <seed> | Google Ads 키워드 플래너 키워드 아이디어 | 3 |
/blog google report <type> | PDF/HTML 성능 리포트 | -- |
/blog google quotas | 모든 API의 속도 제한 표시 | -- |
PageSpeed + CrUX
/blog google pagespeed <url>
게시된 블로그 게시물에 대한 Lighthouse 실험실 데이터 + CrUX 필드 데이터 결합.
스크립트: python3 skills/blog-google/scripts/run.py pagespeed_check <url> --json
참고: references/api-reference.md
출력은 실험실 점수(특정 시점의 Lighthouse)와 필드 데이터(28일 Chrome 사용자 메트릭)를 병합합니다. CrUX는 먼저 URL 수준을 시도하고, 실패하면 사이트 수준으로 대체합니다.
/blog google crux <url>
CrUX 필드 데이터만 (Lighthouse 실행 없음). 더 빠릅니다.
스크립트: python3 skills/blog-google/scripts/run.py pagespeed_check <url> --crux-only --json
/blog google crux-history <url>
25주 CrUX 기록 추세. CWV 메트릭이 개선 중인지, 안정적인지, 저하 중인지 보여줍니다.
스크립트: python3 skills/blog-google/scripts/run.py crux_history <url> --json
Search Console
/blog google gsc <property>
검색 분석: 지난 28일간의 클릭수, 노출수, CTR, 순위.
스크립트: python3 skills/blog-google/scripts/run.py gsc_query --property <property> --json
기본값: 28일, 차원=쿼리,페이지, 유형=웹, 최대 1000개.
빠른 성과 감지 포함: 순위 4-10위에 높은 노출수를 가진 쿼리.
/blog google inspect <url>
URL 검사: Google의 실제 색인 상태.
스크립트: python3 skills/blog-google/scripts/run.py gsc_inspect <url> --json
반환 값: 결과(PASS/FAIL), 적용 범위 상태, robots.txt 상태, 색인 상태, 페이지 가져오기 상태, 표준 URL 선택, 모바일 사용성, 리치 결과.
일괄 검사: python3 skills/blog-google/scripts/run.py gsc_inspect --batch <file> --json
Indexing API
/blog google index <url>
Google에 URL 업데이트를 알립니다. 새 블로그 게시물을 더 빠르게 색인화하기 위해 제출합니다.
스크립트: python3 skills/blog-google/scripts/run.py indexing_notify <url> --json
참고: references/api-reference.md
Indexing API는 공식적으로 JobPosting 및 BroadcastEvent/VideoObject 페이지용입니다. 항상 이 제한을 사용자에게 알리세요. 일일 할당량: 게시 요청 200개.
일괄 처리: python3 skills/blog-google/scripts/run.py indexing_notify --batch <file> --json
GA4 트래픽
/blog google ga4 [property-id]
유기적 트래픽 리포트: 일일 세션, 사용자, 페이지뷰, 이탈률, 참여도.
스크립트: python3 skills/blog-google/scripts/run.py ga4_report --property <id> --json
기본값: 28일, 유기적 검색 채널 그룹으로 필터링.
상위 랜딩 페이지: python3 skills/blog-google/scripts/run.py ga4_report --property <id> --report top-pages --json
YouTube (동영상 검색)
YouTube 언급은 가장 강력한 AI 가시성 상관 관계(0.737, Ahrefs 75K 브랜드)를 가집니다. 무료이며 API 키만 필요합니다. blog-write 및 blog-rewrite에서 동영상 임베딩에 사용됩니다.
/blog google youtube <query>
블로그 주제와 관련된 동영상을 YouTube에서 검색합니다.
스크립트: python3 skills/blog-google/scripts/run.py youtube_search search "<query>" --json
할당량: 검색당 100유닛 (하루 10,000유닛 무료).
반환: 제목, 채널, 조회수, 좋아요, 길이, 설명, 태그.
동영상 세부 정보 + 댓글: python3 skills/blog-google/scripts/run.py youtube_search video <video_id> --json
NLP 콘텐츠 분석
Google 자체 엔티티/감정 분석. 블로그 콘텐츠의 E-E-A-T 점수를 향상시킵니다.
/blog google nlp <url-or-text>
전체 NLP 분석: 엔티티, 감정, 콘텐츠 분류.
스크립트: python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --json
무료 등급: 월 5,000유닛. GCP 프로젝트에서 결제가 활성화되어야 합니다.
엔티티 추출만: python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --features entities --json
키워드 리서치 (Google Ads)
최고 수준의 키워드 볼륨 데이터. Google Ads 계정 필요 (등급 3).
/blog google keywords <seed>
시드 단어에서 블로그 주제 연구를 위한 키워드 아이디어를 생성합니다.
스크립트: python3 skills/blog-google/scripts/run.py keyword_planner ideas "<seed>" --json
볼륨 조회: python3 skills/blog-google/scripts/run.py keyword_planner volume "<kw1>,<kw2>" --json
리포트
/blog google report <type>
차트가 포함된 전문적인 PDF/HTML 리포트를 생성합니다.
스크립트: python3 skills/blog-google/scripts/run.py google_report --type <type> --data <json> --domain <domain> --format pdf
| 유형 | 입력 | 출력 |
|---|---|---|
cwv-audit | PSI + CrUX + CrUX 기록 데이터 | 게이지, 타임라인이 포함된 Core Web Vitals 감사 |
gsc-performance | GSC 쿼리 데이터 | 쿼리 테이블이 포함된 Search Console 리포트 |
indexation | 일괄 검사 데이터 | 적용 범위 도넛 차트가 포함된 색인 상태 |
full | 모든 데이터 결합 | 종합적인 Google SEO 리포트 |
참고: PDF 생성에는 시스템 라이브러리가 필요합니다: sudo apt install libpango1.0-dev libcairo2-dev.
weasyprint를 사용할 수 없는 경우 HTML로 대체됩니다.
속도 제한
| API | 분당 | 일일 | 인증 |
|---|---|---|---|
| PSI v5 | 240 QPM | 25,000 QPD | API 키 |
| CrUX + 기록 | 150 QPM (공유) | 무제한 | API 키 |
| GSC 검색 분석 | 사이트당 1,200 QPM | 3천만 QPD | 서비스 계정 |
| GSC URL 검사 | 600 QPM | 사이트당 2,000 QPD | 서비스 계정 |
| Indexing API | 380 RPM | 일 200건 게시 | 서비스 계정 |
| GA4 데이터 API | 동시 10개 | ~25,000 토큰/일 | 서비스 계정 |
| YouTube 데이터 | -- | 10,000 유닛/일 | API 키 |
| NLP API | -- | 5,000 유닛/월 | API 키 (결제 필요) |
상세 할당량 관리는 references/rate-limits-quotas.md를 읽으세요.
블로그 워크플로 통합
이 스킬은 사용자가 직접 호출할 수 있을 뿐만 아니라(/blog google pagespeed)
내부적으로 다른 블로그 하위 스킬에서도 호출됩니다:
- blog-seo-check: 게시된 게시물 URL에 PSI + CrUX를 실행하여 실시간 CWV 데이터 획득
- blog-rewrite: NLP 엔티티 분석을 통해 E-E-A-T 엔티티 격차 식별
- blog-geo: 실제 검색 노출 인사이트를 위한 GSC 성능 데이터
- blog-audit: 모든 게시된 블로그 URL에 대한 일괄 CWV + 색인 상태 검사
- blog-write / blog-rewrite: 동영상 임베딩을 위한 YouTube 검색
자격 증명이 설정되지 않은 경우 정상적으로 대체됩니다.
기술 참고 사항
- INP는 2024년 3월 12일 FID를 대체했습니다. FID를 참조하지 마세요.
- CrUX의 CLS 값은 문자열로 인코딩됩니다(예: "0.05"). 스크립트가 구문 분석을 처리합니다.
- CrUX 404 = 인증 오류가 아닌, Chrome 트래픽 부족을 의미합니다.
- 검색 분석 데이터는 2-3일의 지연이 있습니다.
- Indexing API는 공식적으로 JobPosting/BroadcastEvent 페이지용입니다.
- 사용된 모든 Google API는 정상 사용 수준에서 무료입니다.
오류 처리
| 시나리오 | 조치 |
|---|---|
| 자격 증명이 설정되지 않음 | /blog google setup 실행. 등급 0 명령어 (API 키만) 나열. |
| 서비스 계정에 GSC 접근 권한 없음 | GSC > 설정 > 사용자 > 추가에 client_email 추가. |
| CrUX 데이터 없음 (404) | Chrome 트래픽 부족. PSI 실험실 데이터로 대체. |
| GA4 속성을 찾을 수 없음 | GA4 관리 > 속성 설정에서 속성 ID 찾기. |
| Indexing API 할당량 초과 | 하루 200개 제한. 가장 중요한 URL 우선 처리. |
| 속도 제한 (429) | 대기 후 지수 백오프로 재시도. |