Pular para o conteúdo
SEO Uptr
SEO UptrCadastre-se

Referência

Referência da API de backlinks: ações, custos e erros

Uma página com os fatos que um monitor precisa saber: quanto custa cada ação, como funciona a paginação e o que a API faz quando algo dá errado.

Ponte de pedra sobre o rio com um pequeno barco navegando por baixo

Ações por custo em créditos

1 crédito = $0,0001. Cada chamada é cobrada uma vez, independentemente do número de linhas, até 1.000 linhas por chamada.
CustoAçõesNotas
Grátis, sem chavedomain, overview, stats, suggestIdeal para dashboards e o verificador de DR
1 créditobulk_dr, compare, top, dr_distribution, tld_breakdownbulk_dr aceita até 2.000 domínios (GET domains= ou corpo POST); compare até 20
2 créditosrefdomains, backlinks, anchors, toppages, anchor_cloud, intersectintersect aceita de 2 a 10 domínios
3 créditossearch, keywordBusca de texto completo em âncoras, títulos e URLs; keyword encontra quem está vinculado com uma âncora exata

Autenticação e códigos de status

Passe a chave como key= ou como cabeçalho bearer. Verifique o código HTTP antes de analisar o corpo.

bash
# header style
curl -s -H "Authorization: Bearer sk_live_..." \
  "https://seouptr.com/api.php?action=anchors&q=yourdomain.com&per=100"

# a cron-safe wrapper
code=$(curl -s -o out.json -w '%{http_code}' "$URL")
case "$code" in
  200) jq '._credits' out.json ;;      # cost and remaining balance
  401) echo 'bad or missing key' ;;
  402) echo 'out of credit: top up' ;;
  *)   echo "unexpected $code" ;;
esac

Parâmetros e erros

ItemValorSignificado
qum domínioO alvo da consulta
page, perper de 10 a 5000Paginação; o número de linhas por chamada é limitado a 1.000, paginação profunda limitada a 50.000
sort, orderorder=asc ou descOrdenação das linhas retornadas
okem todas as respostasSe a chamada foi bem-sucedida
_creditsapenas respostas autenticadasCusto da chamada e saldo restante
HTTP 401chave ausente ou inválidaVerifique a chave ou o cabeçalho
HTTP 402créditos esgotadosRecarregue com USDT (TRC-20)
Carpinteiro medindo madeira e selecionando ferramentas em uma bancada de oficina

Projetando a chamada antes de agendá-la

A maioria dos problemas da API começa na solicitação. Não na resposta. Uma integração de api de backlinks seo é principalmente um conjunto de pequenas decisões tomadas antes da primeira chamada. Defina a chave, o tamanho da página e a ordem de classificação primeiro.

Mantenha a chave fora do script

Armazene a chave em uma variável de ambiente ou em um repositório de segredos, não em um arquivo que você faz commit. Passe-a como o parâmetro key ou como um cabeçalho bearer. O cabeçalho mantém a chave fora de endereços que tendem a acabar em logs.

Não cole uma chave ativa em um ticket ou chat. Trate uma que apareça em um log compartilhado como exposta.

Escolha o tamanho da página com propósito

O parâmetro per varia de 10 a 5000, mas uma chamada é cobrada uma vez para até 1.000 linhas, então páginas maiores significam menos cobranças. Digamos que você precise de 3.400 linhas. Isso requer quatro chamadas de 1.000 linhas, não 340 chamadas de 10.

Mantenha o tamanho da página igual entre execuções para que os arquivos fiquem alinhados.

Fixe a ordem de classificação

Defina sort e order explicitamente em vez de confiar em um padrão. Parâmetros idênticos tornam a saída comparável de semana para semana, para que um diff mostre mudança real e não linhas reorganizadas.

Uma ordem alterada é uma maneira fácil de criar um alarme falso.

Lendo os números

Os dados são nosso próprio grafo de links: 181.132.097 domínios, 2.774.625.913 links entre domínios e cerca de 798,5 bilhões de backlinks. É atualizado aproximadamente uma vez por mês. Qualquer coisa mais recente que isso não estará nele, é por isso que uma api de backlinks seo é melhor consultada semanalmente.

DR é round(100 · log(ref_domains+1) / log(2·10^7)). É um log. Por isso, 100 domínios de referência pontuam 27, 1.000 pontuam 41 e 10.000 pontuam 55, então dobrar sua contagem de links adiciona apenas alguns pontos. Use DR para classificar sites entre si e a contagem bruta para alertas, como a tabela de severidade faz.

O preço é pré-pago. Não há assinatura e não há mínimo. O crédito de cadastro é $100, que equivale a 1.000.000 de créditos. Compare isso com as unidades da API Ahrefs, vendidas dentro de planos a partir de $129/mês por 200.000 unidades, com pelo menos 50 unidades por solicitação.

O planejamento de custos é uma simples multiplicação. Uma chamada semanal de refdomains para um site custa 2 créditos vezes 4, ou 8 créditos por mês, que é $0,0008. Dez sites custam dez vezes isso. A receita de link perdido e a tarefa de concorrente usam apenas ações da tabela acima.

Lendo um erro sem adivinhar

Um código de erro diz a quem deve agir. Leia dessa forma. A resposta então se torna uma decisão de roteamento, não um mistério. Os dois códigos que mais importam para um monitor são 401 e 402.

401 e 402 são problemas diferentes

Um 401 significa que a chave está ausente ou errada, e nada funcionará até que alguém corrija isso. Um 402 significa que a conta está sem crédito, e um recarregamento resolve. Encaminhe-os para diferentes responsáveis para que a pessoa certa veja a mensagem.

Envie ambos para uma pessoa. Um monitor que falha silenciosamente é pior do que um que nunca foi executado.

Verifique o status antes do corpo

Leia o status HTTP primeiro e o campo ok em segundo. Uma resposta pode ser analisada como JSON e ainda carregar uma falha, então a verificação está completa apenas quando ambas passam. Registre o status em cada execução, inclusive as bem-sucedidas.

Retente apenas o que pode se recuperar

Retentar um 401 desperdiça chamadas e preenche logs com a mesma falha. Um tempo limite de rede é diferente. Retente-o um pequeno número de vezes com uma pausa entre as tentativas, depois pare.

Uma execução que para e alerta é mais útil do que um loop de retentativa que esconde a falha até que o saldo acabe.

Registre o status em cada execução

Escreva o status HTTP e o saldo no log em cada execução, incluindo as bem-sucedidas. Quando uma execução falhar três semanas depois, essa linha será a primeira coisa que você vai querer ver.

Ações gratuitas primeiro

domain, overview, stats e suggest não precisam de chave e não custam nada. Use-os para verificar a sanidade de um nome de domínio, uma ortografia exata ou um tamanho aproximado antes de gastar um único crédito em uma ação paga.

Antes de colocar uma chamada no cron

  • O custo da ação é conhecido e multiplicado por execuções por mês.
  • Código de saída e status HTTP são verificados.
  • Um 402 envia um alerta para um humano.
  • As respostas são salvas ordenadas, para que os diffs fiquem limpos.
  • A cadência corresponde à atualização mensal.
Jardineiro organizando plantas em fileiras organizadas em um jardim

Notas sobre paginação

A ordem importa. Use per=1000 para snapshots e mantenha o mesmo sort e order todas as semanas. Se a ordem mudar entre as execuções, um diff mostrará ruído. Essa é uma causa clássica de alarmes falsos.

Sites maiores? Para um site com mais de 1.000 domínios de referência, navegue com page=1, page=2 e assim por diante. Cada página é uma chamada cobrada separadamente. A paginação profunda é limitada a 50.000 linhas, o que cobre quase todos os sites comuns.

Perguntas sobre a referência

Qual ação devo chamar primeiro quando não tenho certeza de como um domínio se parece?
Comece com overview ou domain. Ambas são gratuitas e não precisam de chave, e mostram um tamanho aproximado e a forma básica dos dados. Gaste créditos em refdomains ou anchors apenas depois disso.
Quanto custa uma verificação completa de um domínio?
Some os créditos de cada ação, depois multiplique por quantas vezes ela é executada. Imagine uma chamada refdomains, uma chamada anchors e uma chamada tld_breakdown em um domínio, semanalmente. Isso é 2 + 2 + 1 = 5 créditos por execução, ou $0,0005. Em quatro semanas, chega a cerca de $0,002.
Por que duas contagens para o mesmo domínio podem não coincidir?
Compare o semelhante com o semelhante: a mesma ação, os mesmos parâmetros e o mesmo período de atualização. Contagens de ações diferentes não são intercambiáveis, e uma contagem feita durante a atualização pode diferir de uma feita uma semana depois.
Como testar um job cron sem gastar créditos?
Execute as ações gratuitas primeiro para verificar a fiação, o tratamento de status e o formato de saída. Depois, faça uma chamada paga para provar os números e limite o job a uma única execução enquanto testa.
A paginação funciona para um site com mais de 1.000 domínios de referência?
Sim. Use page com per. Cada página é uma chamada cobrada separadamente, e a paginação profunda é limitada a 50.000 linhas, o que cobre a maioria dos sites comuns.

Um monitor que sobrevive a uma semana ruim

Um monitor ganha confiança nas semanas em que nada dá certo. Planeje uma resposta lenta, um saldo alterado e um resultado parcial antes da primeira execução. Esses são eventos comuns. Cada um deve deixar uma linha clara no log.

Timeouts e extrações parciais

Defina um timeout em cada chamada, para que uma resposta lenta não possa manter todo o job aberto. Se uma página de uma extração de várias páginas falhar, registre qual página foi e reinicie a partir daí. Você evita pagar duas vezes por linhas que já tem.

Marque um arquivo parcial como parcial em vez de salvá-lo como um snapshot normal. Caso contrário, o próximo diff mostrará uma perda que nunca aconteceu.

Verificações de saldo

Leia _credits em cada resposta autenticada e escreva o saldo restante no log. Um pequeno script pode compará-lo com um piso que você escolher e enviar um aviso antes da próxima execução.

Digamos que o piso seja 500 créditos. Uma execução semanal que custa 40 créditos deixa margem para recarregar antes que um 402 chegue no meio da noite.

Mantenha cada job entediante

Dê a cada job um arquivo e um agendamento. Uma entrada cron que faz três coisas pode falhar de três maneiras, e o log nem sempre pode dizer qual aconteceu. Dois jobs pequenos são mais fáceis de confiar do que um inteligente.

Combine o agendamento com a atualização

Combine o agendamento do job com a atualização mensal em vez do relógio. Uma execução diária retorna o mesmo arquivo na maioria dos dias, o que adiciona custo e ruído sem adicionar informações. Semanalmente geralmente é suficiente.