> ## 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 volumen de búsqueda de palabras clave (KEYWORD_VOLUME)

> Obtén el volumen de búsqueda mensual de hasta 100 palabras clave en un país, con los últimos 12 meses y la competencia entre anunciantes.

`KEYWORD_VOLUME` devuelve, para cada palabra clave, la media de búsquedas mensuales de los últimos 12 meses, las 12 cifras mensuales y la competencia entre anunciantes, para un país por tarea.

| | |
| - | - |
| `taskType` | `KEYWORD_VOLUME` |
| Entrada | `keywords` (1-100, obligatorio), `country` (obligatorio) |
| Créditos | 3 por tarea, sea cual sea el número de palabras clave |
| País | Obligatorio. Solo países disponibles; consulta abajo. |
| Ubicación | No admitida (`422 LOCATION_UNSUPPORTED`). |

## Solicitud

```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 | Obligatorio | Descripción |
| - | - | - |
| `keywords` | Sí | Un array de 1 a 100 palabras clave, de 1 a 80 caracteres cada una tras compactar los espacios. En `KR`, las palabras clave solo contienen letras, dígitos y espacios. |
| `country` | Sí | Un código de país de dos letras. También elige la fuente de datos. |

## Fuentes de datos y países

| País | Fuente (`source`) | Qué se cuenta |
| - | - | - |
| `KR` | Naver (`naver`) | Las búsquedas en Naver. |
| Los demás países disponibles | Google Keyword Planner (`google_ads`) | Todas las búsquedas de Google hechas en ese país, en cualquier idioma. |

Los países disponibles son `KR` y los países que admite la segmentación de Google Ads, con dos excepciones: `CN` y `RU` devuelven `422 REGION_UNSUPPORTED`, porque allí la mayoría de las búsquedas se hacen en Baidu y Yandex. Un país sin fuente devuelve el mismo error. Para la lista exacta, llama a [`GET /v1/capabilities?taskType=KEYWORD_VOLUME`](/es/engines/capacity#consulta-qué-sirve-cada-motor) y lee `countries.supported`.

## Respuesta

Por ejemplo:

```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"
    }
  ]
}
```

El ejemplo muestra dos de los doce meses.

| Campo | Descripción |
| - | - |
| `country`, `source` | El país y la fuente de datos que respondió. |
| `fetchedAt` | Cuándo se leyeron las cifras. |
| `keywords` | Una fila por palabra clave solicitada, incluidas las que dan cero. |
| `keywords[].searchVolume` | La media de `monthlySearches`. `0` indica que no hay búsquedas medibles. `null` en `KR` cuando no se pudieron estimar los meses (consulta abajo). |
| `keywords[].monthlySearches` | Hasta 12 entradas `{ month, searchVolume }`, con `month` en formato `YYYY-MM`, empezando por la más antigua. Vacío cuando la fuente no tiene serie para la palabra clave. |
| `keywords[].last30Days` | Solo `KR`: el recuento de Naver de los últimos 30 días. `null` en los demás países. |
| `keywords[].competition` | Competencia entre anunciantes: `low`, `medium`, `high`, o `null` cuando la fuente no la indica. |

En `KR`, cada mes reparte el recuento de 30 días de Naver según su tendencia de búsqueda diaria. Cuando la tendencia cubre menos de 25 de esos 30 días, `searchVolume` es `null`, `monthlySearches` está vacío y `last30Days` mantiene el recuento.

## Límites y errores

* Un `country` ausente o mal formado, un array `keywords` vacío o demasiado grande, o una palabra clave de más de 80 caracteres devuelve `422 VALIDATION_ERROR` con el nombre del campo.
* `CN`, `RU` y los países sin fuente devuelven `422 REGION_UNSUPPORTED`.
* `KEYWORD_VOLUME` ignora `markdown`, `rawResponse` y `searchQueries`. Rechaza `html` y `analysis` con `422` y `citationAnalysis` con `400`; consulta [flags no admitidos](/es/engines/response-options.md#flags-no-admitidos).
* Los demás errores de solicitud se enumeran en [Errores](/es/concepts/errors.md).

## Relacionado

* [Prompt Research](/es/research/prompt-research.md) para convertir un tema en prompts que seguir
* [Regiones y ubicación](/es/engines/capacity.md)


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