Tópicos

API + MCP

GET/v3/content-helper/topics

Este endpoint consome um valor base de 1000 unidades por solicitação, mais 500 unidades se você solicitar uma URL para pontuar.

A análise é executada sob demanda nas páginas que atualmente estão ranqueando para a palavra-chave, então a primeira solicitação para uma palavra-chave leva alguns segundos. Os resultados são armazenados em cache, e solicitações repetidas são atendidas a partir do cache sem custo.

São usadas apenas SERPs que a Ahrefs já coletou, e nenhuma nova SERP é coletada. Se tivermos coletado uma SERP para a palavra-chave e o país nos últimos 90 dias, o endpoint retorna um erro 400 e nenhuma unidade é consumida.

Parâmetros de consulta

keywordstringObrigatório

A palavra-chave para a qual analisar a SERP.

countrystringObrigatório

Um código de país de duas letras (ISO 3166-1 alpha-2).

Valores permitidos:adaeafagaialamaoarasatauawazba…

top_competitorsinteger

Quantas das páginas com melhor ranqueamento analisar. Menos páginas tornam a análise mais rápida, mas com menos abrangência.

Padrão:10

target_urlstring (url)

(500 unidades) Uma página sua para pontuar em relação aos mesmos tópicos, por exemplo, um rascunho que você está escrevendo ou uma página que você quer melhorar. A página é obtida em tempo real. Consome unidades adicionais da API a cada vez (a pontuação dela não é armazenada em cache).

outputstring

O formato de saída.

Valores permitidos:jsonphp

Respostas

topicsarray<object>

avg_scorenumber (float)

A pontuação média de cobertura deste tópico, de 0 a 100, nas páginas que puderam ser analisadas. Um valor alto significa que o tópico é bem coberto pelas páginas que já ranqueiam. Nulo quando nenhuma das páginas pôde ser analisada.

descriptionstring

Sobre o que trata o tópico principal, conforme identificado a partir das páginas concorrentes.

pagesarray<object>

Cobertura deste tópico por página: um registro com os campos url, position (a posição da página na SERP), score (0–100) e extracts (trechos da página que cobrem o tópico). score e extracts são nulos e vazios para uma página cujo conteúdo não pôde ser recuperado, o que é diferente de uma página cuja pontuação foi zero.

urlstring (url)

positioninteger

scoreinteger

extractsarray<string>

pages_coveringinteger

Quantas das páginas analisadas cobrem este tópico (uma pontuação diferente de zero).

serp_datestring (date)

Quando a SERP analisada foi coletada.

targetobject or null

Como a página informada como target_url cobre este tópico. Nulo quando target_url não foi informado.

urlstring (url)

scoreinteger

extractsarray<string>

topicstring

O nome do tópico principal coberto pelas páginas com melhor ranqueamento.