> ## 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 recherche des mots-clés (KEYWORD_VOLUME)

> Obtenez le volume de recherche mensuel de 100 mots-clés au plus dans un pays, avec les 12 derniers mois et la concurrence entre annonceurs.

`KEYWORD_VOLUME` renvoie, pour un pays par tâche, la moyenne mensuelle des recherches de chaque mot-clé sur les 12 derniers mois, les 12 chiffres mensuels et la concurrence entre annonceurs.

| | |
| - | - |
| `taskType` | `KEYWORD_VOLUME` |
| Entrée | `keywords` (1-100, obligatoire), `country` (obligatoire) |
| Crédits | 3 par tâche, quel que soit le nombre de mots-clés |
| Pays | Obligatoire. Pays servis uniquement ; voir ci-dessous. |
| Position | Non prise en charge (`422 LOCATION_UNSUPPORTED`). |

## Requête

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

## Paramètres

| Champ | Obligatoire | Description |
| - | - | - |
| `keywords` | Oui | Un tableau de 1 à 100 mots-clés, de 1 à 80 caractères chacun une fois les espaces regroupés. En `KR`, les mots-clés ne contiennent que des lettres, des chiffres et des espaces. |
| `country` | Oui | Un code pays à deux lettres. Il choisit aussi la source des données. |

## Sources de données et pays

| Pays | Source (`source`) | Ce qui est compté |
| - | - | - |
| `KR` | Naver (`naver`) | Les recherches sur Naver. |
| Tout autre pays servi | Google Keyword Planner (`google_ads`) | Toutes les recherches Google faites dans ce pays, dans n'importe quelle langue. |

Les pays servis sont `KR` et les pays ciblables par Google Ads, à deux exceptions près : `CN` et `RU` renvoient `422 REGION_UNSUPPORTED`, car Baidu et Yandex y servent la plupart des recherches. Un pays sans source renvoie la même erreur. Pour la liste exacte, appelez [`GET /v1/capabilities?taskType=KEYWORD_VOLUME`](/fr/engines/capacity#lister-ce-que-sert-chaque-moteur) et lisez `countries.supported`.

## Réponse

Par exemple :

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

L'exemple montre deux des douze mois.

| Champ | Description |
| - | - |
| `country`, `source` | Le pays et la source de données qui a répondu. |
| `fetchedAt` | Le moment où les chiffres ont été lus. |
| `keywords` | Une ligne par mot-clé demandé, y compris à zéro. |
| `keywords[].searchVolume` | La moyenne de `monthlySearches`. `0` indique aucune recherche mesurable. `null` en `KR` quand les mois n'ont pas pu être estimés (voir ci-dessous). |
| `keywords[].monthlySearches` | Jusqu'à 12 entrées `{ month, searchVolume }`, `month` au format `YYYY-MM`, du plus ancien au plus récent. Vide quand la source n'a pas de série pour le mot-clé. |
| `keywords[].last30Days` | `KR` uniquement : le compte Naver des 30 derniers jours. `null` ailleurs. |
| `keywords[].competition` | La concurrence entre annonceurs : `low`, `medium`, `high`, ou `null` quand la source n'en donne pas. |

En `KR`, chaque mois répartit le compte Naver sur 30 jours selon la tendance de recherche quotidienne de Naver. Quand la tendance couvre moins de 25 de ces 30 jours, `searchVolume` vaut `null`, `monthlySearches` est vide et `last30Days` garde le compte.

## Limites et erreurs

* Un `country` absent ou mal formé, un tableau `keywords` vide ou trop long, ou un mot-clé de plus de 80 caractères renvoie `422 VALIDATION_ERROR` en nommant le champ.
* `CN`, `RU` et les pays sans source renvoient `422 REGION_UNSUPPORTED`.
* `KEYWORD_VOLUME` ignore `markdown`, `rawResponse` et `searchQueries`. Il refuse `html` et `analysis` avec `422` et `citationAnalysis` avec `400` ; voir [flags non pris en charge](/fr/engines/response-options.md#flags-non-pris-en-charge).
* Les autres erreurs de requête sont listées dans [Erreurs](/fr/concepts/errors.md).

## Voir aussi

* [Prompt Research](/fr/research/prompt-research.md) pour transformer un sujet en prompts à suivre
* [Régions et position](/fr/engines/capacity.md)


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