Blog Google: Dados da API Google para Desempenho de Blog
Acesso direto às APIs de SEO do Google para análise de desempenho de blog. Fornece métricas reais do Chrome, status de indexação, desempenho de pesquisa, análise de entidades, descoberta de vídeos do YouTube, volumes de palavras-chave e relatórios de desempenho em PDF/HTML.
Todas as APIs são gratuitas em níveis normais de uso. A configuração requer um projeto do Google Cloud com chave de API e/ou conta de serviço.
Pré-requisitos
Sempre verifique as credenciais antes de executar qualquer comando:
python3 skills/blog-google/scripts/run.py google_auth --check --json
Arquivo de configuração: ~/.config/claude-seo/google-api.json (compartilhado com claude-seo)
{
"api_key": "AIzaSy...",
"oauth_client_path": "/caminho/para/client_secret.json",
"default_property": "sc-domain:example.com",
"ga4_property_id": "properties/123456789",
"ads_developer_token": "...",
"ads_customer_id": "123-456-7890"
}
Se estiver faltando, leia references/auth-setup.md e oriente o usuário na configuração.
Níveis de Credencial
| Nível | Detecção | Comandos Disponíveis |
|---|---|---|
| 0 (Chave de API) | api_key presente | pagespeed, crux, crux-history, youtube, nlp |
| 1 (OAuth/Conta de Serviço) | + Token OAuth ou conta de serviço | Nível 0 + gsc, inspect, index |
| 2 (Completo) | + ga4_property_id configurado | Nível 1 + ga4 |
| 3 (Ads) | + ads_developer_token + ads_customer_id | Nível 2 + keywords |
Sempre comunique o nível detectado antes de executar comandos.
Referência Rápida
| Comando | O que faz | Nível |
|---|---|---|
/blog google setup | Verificar/configurar credenciais da API | -- |
/blog google pagespeed <url> | Dados de campo PSI Lighthouse + CrUX | 0 |
/blog google crux <url> | Apenas dados de campo CrUX (métricas p75) | 0 |
/blog google crux-history <url> | Análise de tendência CWV de 25 semanas | 0 |
/blog google youtube <query> | Pesquisa de vídeos no YouTube (visualizações, likes, duração) | 0 |
/blog google nlp <url-ou-texto> | Extração de entidades NLP + sentimento | 0 |
/blog google gsc <propriedade> | Search Console: cliques, impressões, CTR, posição | 1 |
/blog google inspect <url> | Inspeção de URL: status de indexação, canônica | 1 |
/blog google index <url> | Enviar URL para a API de Indexação | 1 |
/blog google ga4 [id-propriedade] | Relatório de tráfego orgânico GA4 | 2 |
/blog google keywords <semente> | Ideias de palavras-chave do Planejador de Palavras-chave do Google Ads | 3 |
/blog google report <tipo> | Relatório de desempenho em PDF/HTML | -- |
/blog google quotas | Mostrar limites de taxa para todas as APIs | -- |
PageSpeed + CrUX
/blog google pagespeed <url>
Dados combinados de laboratório Lighthouse + campo CrUX para uma postagem de blog publicada.
Script: python3 skills/blog-google/scripts/run.py pagespeed_check <url> --json
Referência: references/api-reference.md
A saída mescla pontuações de laboratório (Lighthouse pontual) com dados de campo (métricas do Chrome de 28 dias). O CrUX tenta primeiro no nível da URL e, em caso de falha, usa o nível de origem.
/blog google crux <url>
Apenas dados de campo CrUX (sem execução do Lighthouse). Mais rápido.
Script: python3 skills/blog-google/scripts/run.py pagespeed_check <url> --crux-only --json
/blog google crux-history <url>
Tendências do histórico CrUX de 25 semanas. Mostra se as métricas CWV estão melhorando, estáveis ou degradando.
Script: python3 skills/blog-google/scripts/run.py crux_history <url> --json
Search Console
/blog google gsc <propriedade>
Análise de Pesquisa: cliques, impressões, CTR, posição nos últimos 28 dias.
Script: python3 skills/blog-google/scripts/run.py gsc_query --property <propriedade> --json
Padrão: 28 dias, dimensões=consulta,página, tipo=web, limite=1000.
Inclui detecção de ganhos rápidos: consultas na posição 4-10 com altas impressões.
/blog google inspect <url>
Inspeção de URL: status de indexação em tempo real do Google.
Script: python3 skills/blog-google/scripts/run.py gsc_inspect <url> --json
Retorna: veredito (APROVADO/REPROVADO), estado de cobertura, status do robots.txt, estado de indexação, estado de busca da página, seleção canônica, usabilidade móvel, resultados ricos.
Para inspeção em lote: python3 skills/blog-google/scripts/run.py gsc_inspect --batch <arquivo> --json
API de Indexação
/blog google index <url>
Notificar o Google sobre uma atualização de URL. Enviar novas postagens de blog para indexação mais rápida.
Script: python3 skills/blog-google/scripts/run.py indexing_notify <url> --json
Referência: references/api-reference.md
A API de Indexação é oficialmente para páginas de JobPosting e BroadcastEvent/VideoObject. Sempre informe o usuário sobre essa restrição. Cota diária: 200 requisições de publicação.
Para lote: python3 skills/blog-google/scripts/run.py indexing_notify --batch <arquivo> --json
Tráfego GA4
/blog google ga4 [id-propriedade]
Relatório de tráfego orgânico: sessões diárias, usuários, visualizações de página, taxa de rejeição, engajamento.
Script: python3 skills/blog-google/scripts/run.py ga4_report --property <id> --json
Padrão: 28 dias, filtrado para grupo de canal de pesquisa orgânica.
Para principais páginas de destino: python3 skills/blog-google/scripts/run.py ga4_report --property <id> --report top-pages --json
YouTube (Descoberta de Vídeos)
As menções no YouTube têm a correlação mais forte com visibilidade de IA (0,737, Ahrefs 75K marcas). Gratuito, apenas chave de API. Usado por blog-write e blog-rewrite para incorporação de vídeos.
/blog google youtube <consulta>
Pesquisar no YouTube por vídeos relevantes para um tópico de blog.
Script: python3 skills/blog-google/scripts/run.py youtube_search search "<consulta>" --json
Cota: 100 unidades por pesquisa (10.000 unidades/dia gratuitas).
Retorna: título, canal, visualizações, likes, duração, descrição, tags.
Para detalhes do vídeo + comentários: python3 skills/blog-google/scripts/run.py youtube_search video <video_id> --json
Análise de Conteúdo NLP
Análise de entidades/sentimento do próprio Google. Melhora a pontuação E-E-A-T para conteúdo de blog.
/blog google nlp <url-ou-texto>
Análise NLP completa: entidades, sentimento, classificação de conteúdo.
Script: python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --json
Nível gratuito: 5.000 unidades/mês. Requer faturamento ativado no projeto GCP.
Para extração apenas de entidades: python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --features entities --json
Pesquisa de Palavras-chave (Google Ads)
Dados de volume de palavras-chave padrão ouro. Requer uma conta do Google Ads (Nível 3).
/blog google keywords <semente>
Gerar ideias de palavras-chave a partir de termos semente para pesquisa de tópicos de blog.
Script: python3 skills/blog-google/scripts/run.py keyword_planner ideas "<semente>" --json
Para consulta de volume: python3 skills/blog-google/scripts/run.py keyword_planner volume "<kw1>,<kw2>" --json
Relatórios
/blog google report <tipo>
Gerar um relatório profissional em PDF/HTML com gráficos.
Script: python3 skills/blog-google/scripts/run.py google_report --type <tipo> --data <json> --domain <dominio> --format pdf
| Tipo | Entrada | Saída |
|---|---|---|
cwv-audit | Dados PSI + CrUX + Histórico CrUX | Auditoria Core Web Vitals com medidores, linhas do tempo |
gsc-performance | Dados de consulta GSC | Relatório do Search Console com tabelas de consulta |
indexation | Dados de inspeção em lote | Status de indexação com gráfico de rosca de cobertura |
full | Todos os dados combinados | Relatório SEO abrangente do Google |
Nota: A geração de PDF requer bibliotecas do sistema: sudo apt install libpango1.0-dev libcairo2-dev.
Faz fallback para HTML se o weasyprint não estiver disponível.
Limites de Taxa
| API | Por Minuto | Por Dia | Autenticação |
|---|---|---|---|
| PSI v5 | 240 QPM | 25.000 QPD | Chave de API |
| CrUX + Histórico | 150 QPM (compartilhado) | Ilimitado | Chave de API |
| GSC Search Analytics | 1.200 QPM/site | 30M QPD | Conta de Serviço |
| GSC URL Inspection | 600 QPM | 2.000 QPD/site | Conta de Serviço |
| Indexing API | 380 RPM | 200 publicações/dia | Conta de Serviço |
| GA4 Data API | 10 concorrentes | ~25K tokens/dia | Conta de Serviço |
| YouTube Data | -- | 10.000 unidades/dia | Chave de API |
| NLP API | -- | 5.000 unidades/mês | Chave de API (faturamento) |
Leia references/rate-limits-quotas.md para gerenciamento detalhado de cotas.
Integração com Fluxo de Trabalho do Blog
Esta skill pode ser invocada pelo usuário (/blog google pagespeed) e também
chamada internamente por outras sub-skills do blog:
- blog-seo-check: Executa PSI + CrUX na URL da postagem publicada para dados CWV em tempo real
- blog-rewrite: Análise de entidades NLP para identificar lacunas de entidade E-E-A-T
- blog-geo: Dados de desempenho do GSC para insights reais de aparência na pesquisa
- blog-audit: Verificações em lote de CWV + indexação em todas as URLs publicadas do blog
- blog-write / blog-rewrite: Pesquisa no YouTube para incorporação de vídeos
Faz fallback graciosamente quando as credenciais não estão configuradas.
Notas Técnicas
- INP substituiu FID em 12 de março de 2024. Nunca faça referência a FID.
- Os valores de CLS do CrUX são codificados como string (ex.: "0.05"). Os scripts lidam com a análise.
- CrUX 404 = tráfego insuficiente do Chrome, não um erro de autenticação.
- Os dados do Search Analytics têm um atraso de 2-3 dias.
- A API de Indexação é oficialmente apenas para páginas de JobPosting/BroadcastEvent.
- Todas as APIs do Google usadas são GRATUITAS em níveis normais de uso.
Tratamento de Erros
| Cenário | Ação |
|---|---|
| Nenhuma credencial configurada | Execute /blog google setup. Liste comandos do Nível 0 (apenas chave de API). |
| Conta de serviço sem acesso ao GSC | Adicione client_email em GSC > Configurações > Usuários > Adicionar. |
| Dados CrUX indisponíveis (404) | Tráfego insuficiente do Chrome. Use dados de laboratório PSI como fallback. |
| Propriedade GA4 não encontrada | Encontre o ID da propriedade em GA4 > Admin > Detalhes da Propriedade. |
| Cota da API de Indexação excedida | Limite de 200/dia. Priorize as URLs mais importantes. |
| Limite de taxa (429) | Aguarde e tente novamente com backoff exponencial. |