Entrada: API
API da ferramenta de verificação de DR: cada parâmetro e campo, explicados
Referência para a estrutura da solicitação e os dois campos que toda resposta autenticada carrega. Linhas específicas da ação variam, então teste uma chamada antes de analisar.
O serviço é uma API REST que retorna JSON. O CORS está aberto. Uma página do navegador pode chamá-la diretamente. As chaves começam com sk_ e são obtidas na página da conta após o login com Google.
A URL base é https://rankupedia.com/api.php. Autentique-se com key=sk_... na string de consulta ou com o cabeçalho Authorization: Bearer sk_..., conforme preferir seu cliente. Quatro ações não exigem autenticação: domain, overview, stats e suggest.
Uma ferramenta de verificação de DR só é útil quando você consegue analisar sua saída. O exemplo abaixo é o caso útil mais simples, e as seções seguintes cobrem as partes que as pessoas costumam errar.
Uma chamada, anotada
A ação gratuita overview. Substitua o domínio pelo seu próprio.
curl "https://rankupedia.com/api.php?action=overview&q=nytimes.com"
# authenticated listing, 100 rows per page:
curl -H "Authorization: Bearer sk_live_..." \
"https://rankupedia.com/api.php?action=refdomains&q=nytimes.com&per=100&page=1&order=desc"Anatomia de uma solicitação
Escolha a ação
O valor action seleciona a operação e o preço. As ações gratuitas estão listadas na tabela de custos.
Nomeie o destino
O valor q é um domínio nu, como nytimes.com, sem esquema ou caminho.
Adicione credenciais se a ação for paga
Ou key na string de consulta ou o cabeçalho Bearer. Os cabeçalhos mantêm as chaves fora dos logs do servidor e do histórico do navegador.
Página e ordenação
page e per dividem os resultados e sort com order os organiza. A paginação para em 50.000 linhas.
Preparando a lista de domínios antes da primeira chamada
Muitos resultados estranhos começam com a entrada, não com o servidor. Limpe a lista uma vez, depois envie-a.
Remova tudo que não for um domínio nu. Um endereço colado com um caminho adiciona caracteres que o valor q não espera, então remova o esquema, o caminho e qualquer barra final.
Remova o esquema e o caminho
Converta https://shop.example.org/blog/ para shop.example.org antes da chamada. O valor q aceita um domínio nu, então o caminho é descartado aqui em vez de enviado.
Planilhas ocultam esses detalhes dentro de uma célula. Um filtro rápido para barras e dois pontos captura a maioria deles.
Coloque os nomes em minúsculas e remova duplicatas
Nomes de domínio não diferenciam maiúsculas de minúsculas, então Example.COM e example.com referem-se a um único destino. Enviar ambos gasta créditos duas vezes por uma única resposta.
Remova duplicatas antes de contar as chamadas. Uma lista de 2.100 nomes com 300 repetições precisa de duas chamadas bulk_dr brutas, mas depois de removidas as duplicatas, seus 1.800 nomes exclusivos cabem em uma única chamada.
Decida entre o domínio raiz e um subdomínio
Um subdomínio como blog.example.org é seu próprio nome em sua lista. Decida sobre qual deles sua pergunta se aplica antes de enviar qualquer coisa.
Se a pergunta abrange todo o site, envie o nome raiz. Se abrange um subdomínio, teste esse nome exato e leia a resposta como pertencente apenas a ele.
Escreva a decisão nas notas do trabalho, para que a próxima execução, talvez por outra pessoa, aplique a mesma regra.
Parâmetros de consulta
| Parâmetro | Significado | Notas |
|---|---|---|
| action | Qual operação executar | Obrigatório; consulte a tabela de custos |
| q | Domínio de destino | Exemplo: nytimes.com |
| key | Chave da API | Ou use o cabeçalho Bearer |
| page | Número da página dos resultados | Paginação profunda é limitada a 50.000 |
| per | Linhas por página | Aceita de 10 a 5000; uma chamada é uma cobrança, independente da quantidade de linhas |
| sort | Coluna para ordenar | As colunas disponíveis dependem da ação |
| order | asc ou desc | Use junto com sort |
| domains | Lista para bulk_dr | Máximo de 2.000 domínios por vez, via GET ou corpo POST |
Paginando uma listagem longa
Ações de listagem retornam linhas em páginas. Dois parâmetros controlam a fatia: page escolhe qual fatia, e per define quantas linhas ela contém. Per aceita valores de 10 a 5000.
Escolha o tamanho da página primeiro. Um per maior reduz o número de chamadas, e a cobrança conta chamadas, não linhas.
Ordene antes de paginar
Sort e order decidem quais linhas aparecem na página um. Defina ambos em cada chamada de uma série, para que cada página venha da mesma ordenação.
Use desc em uma coluna de métrica quando quiser as linhas mais fortes primeiro, e asc quando procurar pelas mais fracas. Os nomes de colunas disponíveis dependem da ação.
Confirme a ordem com um teste pequeno de duas páginas antes de confiar em uma execução longa.
Pare no limite de 50.000 linhas
A paginação profunda para em 50.000 linhas. Após esse ponto, a chamada não retorna nada novo, então um loop que continua paginando está gastando créditos à toa.
Restrinja a pergunta ou divida o trabalho em execuções menores. Uma segunda consulta com um destino diferente geralmente é mais limpa do que uma paginação mais profunda.
Um limite de profundidade é uma propriedade da listagem, então se aplica a todos os clientes que a chamam.
Encerre o loop em uma página curta
Pare quando uma página retornar menos linhas do que per. Esse é o sinal usual de que a listagem acabou.
Combine esse teste com a verificação de saldo na entrada de solução de problemas, para que o loop termine na última página ou quando o saldo estiver baixo, o que ocorrer primeiro.
Campos presentes em todas as respostas
ok
Um booleano. True significa que a chamada foi concluída. False significa que não foi, e o status HTTP indica o motivo.
_credits
Aparece em chamadas autenticadas. Relata o custo desta chamada e seu saldo restante em créditos, permitindo que você pare um loop antes que o saldo acabe.
Os nomes dos campos em nível de linha para cada ação são visíveis em uma resposta ao vivo. Não os reproduzimos nesta entrada para que não desviem do serviço.
Testando uma chamada antes de escrever um loop
Escolha um domínio que você conhece
Escolha um site cujo perfil você possa julgar por suas próprias páginas. Um domínio que você conhece torna um número estranho fácil de identificar.
Envie uma chamada gratuita
Execute overview ou domain sem chave. A resposta mostra a forma real do JSON, que é mais confiável do que qualquer descrição, incluindo esta.
Envie uma chamada paga com a menor página
Use per=10 em uma ação de listagem. Você verá os campos de linha e o valor _credits antes de escalar.
Leia _credits, depois escale
Multiplique o custo de uma chamada pelo número de chamadas no seu plano. Se o total for maior que o saldo, reduza o plano antes que o loop comece.
Antes de implantar um cliente
- Verifique ok antes de ler qualquer outro campo
- Registre _credits em cada chamada
- Trate os dados como uma captura mensal
- Trate 401 e 402 separadamente, consulte a entrada de solução de problemas
- Mantenha a chave fora do código front-end
Notas sobre lotes
A ação bulk_dr aceita até 2.000 domínios por chamada. Envie-os como um valor de consulta domains, ou como um corpo POST quando a lista for longa demais para uma URL.
compare aceita até 20 domínios e intersect aceita de 2 a 10. Intersect responde a uma pergunta: quais sites fazem link para todos os domínios que você nomeia.
Como a cobrança é por chamada, lotes maiores são sempre mais baratos por linha. Eles também falham como uma unidade. Divida por um tamanho que você possa retentar.
Listas longas podem ir em um corpo POST. Leia ok antes de qualquer outra coisa na resposta, porque um lote rejeitado não carrega linhas que você possa usar.
Lendo o JSON sem suposições
Analisadores falham em campos que uma resposta omite. Código que espera todas as chaves em cada linha é frágil, e uma linha curta pode parar todo um trabalho.
Trate campos ausentes como normais
Os campos de linha dependem da ação, então um campo presente em uma listagem pode estar ausente em outra. Atribua um valor padrão a cada campo e continue.
Registre qual campo estava ausente, não apenas que algo falhou. Esse log mostra se o esquema ou seu próprio código mudou.
Mantenha respostas brutas para uma amostra
Salve o JSON bruto das primeiras chamadas em cada novo trabalho. Quando um número parecer errado mais tarde, o texto salvo resolve a questão mais rápido do que a memória.
Armazene a amostra com sua data e nome da ação. Uma atualização mensal significa que a mesma chamada pode retornar linhas diferentes no próximo mês.
Ações por família
| Família | Ações | Uso típico |
|---|---|---|
| Gratuito | domain, overview, stats, suggest | Consultas rápidas e autocompletar |
| Pontuação | bulk_dr, compare, dr_distribution | Triagem de listas e conjuntos de pares |
| Listagem | refdomains, backlinks, anchors, toppages, anchor_cloud | Auditoria de um site |
| Pesquisa | search, keyword, intersect | Encontrando quem faz link com um anchor específico ou para vários concorrentes |
Os nomes dos campos em nível de linha diferem por ação e não estão listados aqui. Chame o endpoint com uma ação gratuita em um domínio que você conhece e leia o JSON, que é a única fonte autoritativa.
Perguntas sobre parâmetros que desenvolvedores fazem
Quatro perguntas sobre parâmetros cobrem a maior parte da primeira semana com a API.
Preciso de uma chave para cada chamada?
Não. As ações domain, overview, stats e suggest não precisam de chave. Ações pagas precisam de uma, enviada seja como o parâmetro key ou como um cabeçalho Bearer.
Posso enviar a chave na URL?
Sim, o parâmetro key funciona na string de consulta. O cabeçalho mantém a chave fora do endereço em si, o que muitas equipes preferem para logs e links compartilhados.
E se eu quiser per acima de 5000?
A faixa documentada é de 10 a 5000. Valores fora dela estão fora do que esta entrada descreve, então mantenha o valor dentro da faixa e pague para obter mais.
A distinção entre maiúsculas e minúsculas importa em q?
Nomes de domínio não diferenciam maiúsculas de minúsculas, então coloque o valor em minúsculas antes de enviá-lo. Uma única ortografia facilita comparar resultados entre execuções.
