Integrações de API e Guia para Desenvolvedores

Por que Usar a API do GEO-Score?

Embora o painel do GEO-Score seja poderoso para análises manuais, a API desbloqueia automação em escala. Integre análises GEO diretamente ao seu sistema de gerenciamento de conteúdo, pipeline de CI/CD ou ferramentas de relatório personalizadas para monitorar a visibilidade em busca com IA em todo o seu site automaticamente.

Seja você um desenvolvedor solo automatizando seu próprio fluxo de trabalho ou uma agência gerenciando centenas de sites de clientes, a API oferece acesso programático a todas as funcionalidades disponíveis no painel e mais.

Visão Geral da API

A API do GEO-Score segue convenções RESTful com corpos de requisição e resposta em JSON. Todos os endpoints exigem autenticação via chave de API e retornam estruturas de resposta consistentes.

URL Base

https://api.bloffee.com/v1

Formato de Resposta

Todas as respostas da API seguem uma estrutura JSON consistente com códigos de status e objetos de dados aninhados:

{
  "status": "success",
  "data": {
    "url": "https://example.com/page",
    "geoScore": 85,
    "factors": {...}
  }
}

Autenticação

Toda requisição à API deve incluir sua chave de API no cabeçalho Authorization. Chaves de API estão vinculadas à sua conta e podem ser gerenciadas nas configurações do painel.

Obtendo sua Chave de API

Vá até Painel > Configurações > Chaves de API para gerar uma nova chave. Você pode criar várias chaves com permissões diferentes para diferentes integrações. Cada chave pode ser revogada individualmente sem afetar as outras.

Authorization: Bearer YOUR_API_KEY_HERE

Usando sua Chave de API

Inclua sua chave de API como um Bearer token no cabeçalho Authorization de cada requisição:

curl -X GET \
  https://api.bloffee.com/v1/urls \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoints Disponíveis

A API do GEO-Score fornece endpoints para enviar URLs para análise, recuperar resultados, disparar reanálises e comparar várias URLs. Aqui está um resumo de todos os endpoints disponíveis:

GET/urls

Recupere uma lista paginada de todas as URLs analisadas em sua conta.

GET https://api.bloffee.com/v1/urls?page=1&limit=50

GET/urls/:id

Obtenha os resultados completos de análise para uma URL específica por seu ID exclusivo.

GET https://api.bloffee.com/v1/urls/abc123

POST/urls

Envie uma nova URL para análise GEO. Retorna o ID da análise para consultar os resultados.

POST https://api.bloffee.com/v1/urls

PUT/urls/:id/refresh

Dispare uma nova análise de uma URL previamente analisada.

PUT https://api.bloffee.com/v1/urls/abc123/refresh

GET/compare

Compare pontuações GEO e detalhamentos de fatores em várias URLs lado a lado.

GET https://api.bloffee.com/v1/compare?urls=id1,id2,id3

Exemplos de Código

Comece rapidamente com estes exemplos de código prontos para usar em linguagens de programação populares. Copie, cole e personalize para seu caso de uso específico.

JavaScript (Node.js)

const fetch = require('node-fetch');

const analyzeURL = async (url) => {
  const response = await fetch('https://api.bloffee.com/v1/urls', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url })
  });

  const data = await response.json();
  console.log('GEO Score:', data.data.geoScore);
  return data;
};

analyzeURL('https://example.com/my-page');

Python

import requests

def analyze_url(url):
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.bloffee.com/v1/urls',
        headers=headers,
        json={'url': url}
    )

    data = response.json()
    print(f"GEO Score: {data['data']['geoScore']}")
    return data

analyze_url('https://example.com/my-page')

PHP

<?php
$url = 'https://example.com/my-page';

$data = array('url' => $url);
$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer YOUR_API_KEY
" .
                     "Content-Type: application/json
",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents(
    'https://api.bloffee.com/v1/urls',
    false,
    $context
);

$response = json_decode($result, true);
echo "GEO Score: " . $response['data']['geoScore'];
?>

Webhooks

Webhooks permitem que o GEO-Score envie notificações em tempo real ao seu servidor sempre que eventos importantes ocorrerem. Em vez de consultar a API por atualizações, configure uma URL de webhook e receba retornos de chamada instantâneos.

Configurando Webhooks

Configure seu endpoint de webhook em Painel > Configurações > Webhooks. Você pode selecionar quais eventos disparam notificações e definir um segredo de assinatura personalizado para verificação de payload.

analysis.complete Disparado quando uma análise de URL termina o processamento e os resultados estão disponíveis.
score.changed Disparado quando uma URL reanalisada mostra uma mudança significativa de GEO Score (delta > 5 pontos).
report.generated Disparado quando um relatório agendado ou sob demanda está pronto para download.
url.added Disparado quando uma nova URL é adicionada à sua conta para acompanhamento.

Exemplo de Payload de Webhook

{
  "event": "analysis.complete",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "url_id": "abc123",
    "url": "https://example.com/page",
    "geoScore": 85,
    "previousScore": 78,
    "factors": {
      "readability": 90,
      "comprehensiveness": 82,
      "aiOptimization": 85
    }
  }
}

Ideias de Automação

•Analise automaticamente cada novo post de blog publicado no seu CMS antes que ele entre no ar
•Configure notificações no Slack quando qualquer URL acompanhada cair abaixo de um limite de GEO Score
•Gere relatórios em PDF semanais e envie por email para seus clientes ou stakeholders
•Construa um painel personalizado que combine dados de GEO Score com sua plataforma de analytics
•Dispare reanálise após atualizações de conteúdo para medir o impacto de suas otimizações
•Crie um checklist pré-publicação que exija um GEO Score mínimo antes do conteúdo ir ao ar

Integrações de Terceiros

O GEO-Score se integra a ferramentas e plataformas populares para se encaixar perfeitamente no seu fluxo de trabalho existente. Use nossas integrações nativas ou construa as suas próprias usando a API.

Zapier

Conecte o GEO-Score a 5.000+ apps. Dispare Zaps na conclusão de análises, mudanças de pontuação ou novas URLs adicionadas à sua conta.

WordPress

Instale o plugin GEO-Score para analisar páginas diretamente do editor do WordPress. Veja pontuações GEO em tempo real enquanto escreve e publica.

Slack

Receba notificações instantâneas no Slack para mudanças de pontuação, análises concluídas e relatórios resumidos semanais no canal de sua escolha.

Google Sheets

Sincronize automaticamente os dados de GEO Score com o Google Sheets para relatórios personalizados, análise de tendências e compartilhamento fácil com sua equipe.

HubSpot

Enriqueça sua estratégia de conteúdo no HubSpot com dados de GEO Score. Acompanhe a visibilidade em IA junto com suas métricas de marketing existentes.

Google Analytics

Correlacione melhorias de GEO Score com mudanças no tráfego orgânico. Veja como a otimização para busca com IA impacta seu tráfego no mundo real.

Limites de Taxa

Os limites de taxa da API são baseados no seu plano de assinatura. Requisições que excederem seu limite de taxa receberão uma resposta 429 com um cabeçalho Retry-After indicando quando você pode retomar.

Starter

100

requisições por hora

Pro

1,000

requisições por hora

Enterprise

Personalizado

contate-nos para limites

Os limites de taxa são redefinidos em uma janela móvel de uma hora. Requisições em rajada de até 2x seu limite por hora são permitidas por curtos períodos. Entre em contato com o suporte se precisar de limites maiores.

Próximos Passos

Pronto para começar? Gere sua chave de API na página de configurações do painel e experimente os exemplos de código acima. Nossa documentação da API inclui esquemas detalhados de requisição e resposta para cada endpoint.

Para casos de uso avançados, explore nosso sistema de webhooks para construir integrações orientadas a eventos. Use o endpoint POST /urls para enviar páginas para análise e o endpoint GET /urls/:id para recuperar resultados detalhados.