Visão geral - Impressões

API + MCP

POST/v3/brand-radar/impressions-overview

As solicitações para este endpoint consomem unidades de API com base no parâmetro prompts: solicitações que retornam apenas dados de prompt personalizado são gratuitas, enquanto solicitações que incluem dados de prompt da Ahrefs seguem o preço padrão de unidades de API.

Corpo da solicitação

selectarray<string>Required

Uma lista de campos para retornar.\n\n- brand\n- no_tracked_brands\n- only_competitors_brands\n- only_target_brand\n- target_and_competitors_brands\n- total

Example:["field_a","field_b"]

whereobject

A expressão de filtro. Os seguintes identificadores de coluna são reconhecidos (isso difere dos identificadores reconhecidos pelo parâmetro select).

report_idstring

O ID do relatório a ser usado. Se um for fornecido, outros parâmetros são obtidos do relatório (marca, concorrentes, mercado, país, filtros). Se país ou filtros forem fornecidos, eles substituirão os do relatório. Você pode encontrá-lo na URL do seu relatório do Brand Radar na Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

Uma lista de nomes e sites de marcas para pesquisar.

Default:[]

At least one of names or url_groups is required

namesarray<string>

The names of the brand/competitor

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

The domain of the target

Example:ahrefs.com

scopestringrequired

Scope of the target.

Valores permitidos:urlpathdomainsubdomains

competitorsarray<object>

Uma lista de nomes e sites de concorrentes para pesquisar.

Default:[]

At least one of names or url_groups is required

namesarray<string>

The names of the brand/competitor

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

The domain of the target

Example:ahrefs.com

scopestringrequired

Scope of the target.

Valores permitidos:urlpathdomainsubdomains

data_sourcearray<string>Required

Uma lista de modelos de chatbot. Todos os modelos podem ser combinados entre si. O módulo claude oferece suporte apenas a prompts personalizados.
Os modelos google_ai_overviews_keywords e google_ai_mode_keywords informam a visibilidade de AI Overviews / AI Mode derivada de consultas de pesquisa do Google (palavras-chave), em vez de prompts.

Valores permitidos:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

Uma lista de códigos de país de duas letras (ISO 3166-1 alfa-2).

Valores permitidos:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

O tipo de prompts a usar. Se não for especificado, ambos serão usados. Prompts personalizados exigem que um report_id seja fornecido.

Valores permitidos:ahrefscustom

search_volume_typestring

Os relatórios de visibilidade de IA estão migrando para o volume ajustado para IA. Ele estima melhor a demanda por respostas de IA em chatbots e superfícies de pesquisa com IA. Ele é calculado ajustando o volume de pesquisa do Google pelo uso estimado de cada plataforma de IA em comparação com o Google. Este parâmetro será descontinuado em 30 de setembro de 2026; todas as solicitações usarão o novo volume ajustado para IA.

Valores permitidos:ask_volumekeyword_volume

Default:ask_volume

tags_filterobject

Uma expressão de filtro para tags de prompt. Requer report_id. Usa a sintaxe de filtro com as seguintes restrições: o único nome de campo válido é "tag"; os únicos operadores válidos são: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; a profundidade máxima de aninhamento de and e or é 2.

Example:{"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}

outputstring

O formato de saída.

Valores permitidos:jsoncsvxmlphp

Respostas

metricsarray<object>

brandstring

Nome da marca (a sua marca ou um concorrente informado na solicitação).

no_tracked_brandsinteger

Impressões estimadas de respostas relacionadas ao mercado especificado que não mencionam nenhuma das marcas fornecidas (o valor é zero quando market não é especificado).

only_competitors_brandsinteger

Impressões estimadas de respostas que mencionam apenas marcas de concorrentes.

only_target_brandinteger

Impressões estimadas de respostas que mencionam apenas a sua marca.

target_and_competitors_brandsinteger

Impressões estimadas de respostas que mencionam tanto a sua marca quanto marcas de concorrentes.

totalinteger

Total de impressões estimadas para a sua marca (inclui only_target_brand e target_and_competitors_brands).

curl "https://api.ahrefs.com/v3/brand-radar/impressions-overview" \ -X POST \ -H "Authorization: Bearer $AHREFS_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "select": ["field_a","field_b"], "where": {}, "report_id": "string", "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "data_source": ["chatgpt"], "country": ["ad"], "prompts": "ahrefs", "search_volume_type": "ask_volume", "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "output": "json" }'

{ "metrics": [ { "brand": "string", "no_tracked_brands": 0, "only_competitors_brands": 0, "only_target_brand": 0, "target_and_competitors_brands": 0, "total": 0 } ] }