API de volume de busca de palavras-chave (KEYWORD_VOLUME)

KEYWORD_VOLUME retorna, para cada palavra-chave, a média de buscas mensais dos últimos 12 meses, os 12 números mensais e a concorrência entre anunciantes, em um país por tarefa.


`taskType`	`KEYWORD_VOLUME`
Entrada	`keywords` (1-100, obrigatório), `country` (obrigatório)
Créditos	3 por tarefa, qualquer que seja o número de palavras-chave
País	Obrigatório. Só países atendidos; veja abaixo.
Localização	Não suportada (`422 LOCATION_UNSUPPORTED`).

Requisição

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "KEYWORD_VOLUME", "payload": { "keywords": ["sunscreen", "mineral sunscreen"], "country": "US" } }'

Parâmetros

Campo	Obrigatório	Descrição
`keywords`	Sim	Um array de 1 a 100 palavras-chave, cada uma com 1 a 80 caracteres depois de os espaços em branco serem condensados. Em `KR`, as palavras-chave contêm só letras, dígitos e espaços.
`country`	Sim	Um código de país de duas letras. Ele também escolhe a fonte de dados.

Fontes de dados e países

País	Fonte (`source`)	O que é contado
`KR`	Naver (`naver`)	Buscas no Naver.
Todos os outros países atendidos	Google Keyword Planner (`google_ads`)	Todas as buscas no Google feitas naquele país, em qualquer idioma.

Os países atendidos são KR e os países-alvo do Google Ads, com duas exceções: CN e RU retornam 422 REGION_UNSUPPORTED, porque ali a maioria das buscas é feita no Baidu e no Yandex. Um país sem fonte retorna o mesmo erro. Para a lista exata, chame GET /v1/capabilities?taskType=KEYWORD_VOLUME e leia countries.supported.

Resposta

Por exemplo:

{
  "country": "US",
  "source": "google_ads",
  "fetchedAt": "2026-10-09T13:05:12.000Z",
  "keywords": [
    {
      "keyword": "sunscreen",
      "searchVolume": 110000,
      "monthlySearches": [
        { "month": "2025-09", "searchVolume": 74000 },
        { "month": "2026-08", "searchVolume": 135000 }
      ],
      "last30Days": null,
      "competition": "high"
    }
  ]
}

O exemplo mostra dois dos doze meses.

Campo	Descrição
`country`, `source`	O país e a fonte de dados que respondeu.
`fetchedAt`	Quando os números foram lidos.
`keywords`	Uma linha por palavra-chave pedida, inclusive as com zero.
`keywords[].searchVolume`	A média de `monthlySearches`. `0` indica nenhuma busca mensurável. `null` em `KR` quando os meses não puderam ser estimados (veja abaixo).
`keywords[].monthlySearches`	Até 12 entradas `{ month, searchVolume }`, com `month` no formato `YYYY-MM`, do mais antigo para o mais recente. Vazio quando a fonte não tem série para a palavra-chave.
`keywords[].last30Days`	Só em `KR`: a contagem do Naver dos últimos 30 dias. `null` nos demais países.
`keywords[].competition`	Concorrência entre anunciantes: `low`, `medium`, `high`, ou `null` quando a fonte não informa nenhuma.

Em KR, cada mês distribui a contagem de 30 dias do Naver pela tendência de busca diária do Naver. Quando a tendência cobre menos de 25 desses 30 dias, searchVolume é null, monthlySearches fica vazio e last30Days continua trazendo a contagem.

Limites e erros

Um country ausente ou malformado, um array keywords vazio ou grande demais, ou uma palavra-chave com mais de 80 caracteres retorna 422 VALIDATION_ERROR indicando o campo.
CN, RU e países sem fonte retornam 422 REGION_UNSUPPORTED.
KEYWORD_VOLUME ignora markdown, rawResponse e searchQueries. Recusa html e analysis com 422 e citationAnalysis com 400; veja flags não suportadas.
Os demais erros de requisição estão em Erros.

Relacionados

Prompt Research para transformar um tema em prompts a acompanhar
Regiões e localização

Primeiros passos

Conceitos principais

Mecanismos de resposta

Busca e dados da web

Opções de requisição

Pesquisa

Monitoramento GEO

Conta e dados

API de volume de busca de palavras-chave (KEYWORD_VOLUME)

Requisição

Parâmetros

Fontes de dados e países

Resposta

Limites e erros

Relacionados

​Requisição

​Parâmetros

​Fontes de dados e países

​Resposta

​Limites e erros

​Relacionados

Requisição

Parâmetros

Fontes de dados e países

Resposta

Limites e erros

Relacionados