Integrações de API e Guia para Programadores

Por Que Usar a API do GEO-Score?

Embora o dashboard do GEO-Score seja poderoso para análises manuais, a API desbloqueia automação em escala. Integre análises GEO diretamente no seu sistema de gestão de conteúdo, pipeline CI/CD ou ferramentas de relatórios personalizadas para monitorizar a visibilidade em pesquisas de IA em todo o seu website automaticamente.

Quer seja um programador individual automatizando o seu próprio fluxo de trabalho ou uma agência gerindo centenas de sites de clientes, a API dá-lhe acesso programático a todas as funcionalidades disponíveis no dashboard e mais.

Visão Geral da API

A API do GEO-Score segue convenções RESTful com corpos de pedido e resposta em JSON. Todos os endpoints requerem autenticação via chave 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 estado e objetos de dados aninhados:

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

Autenticação

Cada pedido à API deve incluir a sua chave API no cabeçalho de Autorização. As chaves API estão associadas à sua conta e podem ser geridas nas definições do dashboard.

Obter a Sua Chave API

Navegue para Dashboard > Definições > Chaves API para gerar uma nova chave. Pode criar múltiplas chaves com diferentes permissões para diferentes integrações. Cada chave pode ser revogada individualmente sem afetar as outras.

Authorization: Bearer YOUR_API_KEY_HERE

Usar a Sua Chave API

Inclua a sua chave API como um token Bearer no cabeçalho de Autorização de cada pedido:

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 submeter URLs para análise, obter resultados, acionar re-análises e comparar múltiplos URLs. Aqui está um resumo de todos os endpoints disponíveis:

GET/urls

Obter uma lista paginada de todos os URLs analisados na sua conta.

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

GET/urls/:id

Obter os resultados de análise completos de um URL específico pelo seu ID único.

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

POST/urls

Submeter um novo URL para análise GEO. Retorna o ID da análise para consultar resultados.

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

PUT/urls/:id/refresh

Acionar uma re-análise recente de um URL previamente analisado.

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

GET/compare

Comparar GEO scores e divisões de fatores entre múltiplos 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 a usar em linguagens de programação populares. Copie, cole e personalize para o 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 ao GEO-Score enviar notificações em tempo real para o seu servidor sempre que eventos importantes ocorrem. Em vez de consultar a API para atualizações, configure um URL de webhook e receba callbacks instantâneos.

Configurar Webhooks

Configure o seu endpoint de webhook em Dashboard > Definições > Webhooks. Pode selecionar quais eventos acionam 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 um URL re-analisado mostra uma alteração significativa no GEO Score (delta > 5 pontos).
report.generated Disparado quando um relatório agendado ou sob demanda está pronto para download.
url.added Disparado quando um novo URL é adicionado à 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

•Analisar automaticamente cada novo artigo de blog publicado no seu CMS antes de ir ao ar
•Configurar notificações Slack quando qualquer URL acompanhado cai abaixo de um limite de GEO Score
•Gerar relatórios PDF semanais e enviá-los por email aos seus clientes ou partes interessadas
•Construir um dashboard personalizado que combina dados do GEO Score com a sua plataforma de análise
•Acionar re-análise após atualizações de conteúdo para medir o impacto das suas otimizações
•Criar uma checklist pré-publicação que requer um GEO Score mínimo antes do conteúdo ir ao ar

Integrações de Terceiros

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

Zapier

Conecte o GEO-Score a mais de 5.000 aplicações. Acione Zaps na conclusão de análises, alterações de pontuação ou novos URLs adicionados à sua conta.

WordPress

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

Slack

Receba notificações instantâneas do Slack para alterações de pontuação, análises concluídas e relatórios resumo semanais no seu canal escolhido.

Google Sheets

Sincronize automaticamente dados do GEO Score para Google Sheets para relatórios personalizados, análise de tendências e partilha fácil com a sua equipa.

HubSpot

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

Google Analytics

Correlacione melhorias no GEO Score com alterações no tráfego orgânico. Veja como a otimização de pesquisa de IA impacta o seu tráfego no mundo real.

Limites de Taxa

Os limites de taxa da API são baseados no seu plano de subscrição. Pedidos que excedam o seu limite de taxa receberão uma resposta 429 com um cabeçalho Retry-After indicando quando pode retomar.

Starter

100

pedidos por hora

Pro

1,000

pedidos por hora

Enterprise

Personalizado

contacte-nos para limites

Os limites de taxa reiniciam numa janela de uma hora contínua. Picos de pedidos até 2x o seu limite horário são permitidos por períodos curtos. Contacte o suporte se precisar de limites mais altos.

Próximos Passos

Pronto para começar? Gere a sua chave API na página de definições do dashboard e experimente os exemplos de código acima. A nossa documentação da API inclui esquemas detalhados de pedido e resposta para cada endpoint.

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