> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Receba o volume de busca mensal de até 100 palavras-chave em um país, com os últimos 12 meses e a concorrência entre anunciantes.

`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

```bash theme={"theme":"css-variables"}
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`](/pt/engines/capacity#listar-o-que-cada-mecanismo-atende) e leia `countries.supported`.

## Resposta

Por exemplo:

```json theme={"theme":"css-variables"}
{
  "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](/pt/engines/response-options.md#flags-não-suportadas).
* Os demais erros de requisição estão em [Erros](/pt/concepts/errors.md).

## Relacionados

* [Prompt Research](/pt/research/prompt-research.md) para transformar um tema em prompts a acompanhar
* [Regiões e localização](/pt/engines/capacity.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.