> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/tools/keyword_volume

# keyword_volume

> Google Ads monthly search volume, cost per click and competition for up to a thousand keywords in one call, by country. ₹10 per call; an empty answer is ₹0.

## What it does

Google Ads search volume for a list of keywords in a country, in `data[]`, one row per keyword: `search_volume` (the average monthly searches), `cpc`, `competition` (`LOW`, `MEDIUM`, `HIGH`) with `competition_index`, `low_top_of_page_bid` and `high_top_of_page_bid`, and twelve months of `monthly_searches[]` (`year`, `month`, `search_volume`). Use it to size demand before writing content or buying ads; for relative interest over time use [`keyword_data`](https://parel.si/docs/tools/keyword_data.md), and for where a site ranks use [`rank_check`](https://parel.si/docs/tools/rank_check.md). Keywords are lowercased by the source, and a keyword Google has no volume for is simply missing from `data[]`.

India: `location_code` 2356 with `language_code` `"en"` or `"hi"`; without a location the figures are worldwide.

## Inputs

Generated from the contract captured from staging on 2026-11-05.

| Field | Type | Required | Description |
|---|---|---|---|
| `date_to` | string | no | yyyy-mm-dd, cannot be later than last month |
| `keywords` | array of values | yes | up to 1000 keywords, each max 80 chars / 10 words; lowercased by the API. e.g. ["coffee"] |
| `date_from` | string | no | yyyy-mm-dd, max 4 years back |
| `language_code` | string | no | e.g. "en". e.g. "en" |
| `location_code` | integer | no | 2840 = United States; omitting it returns worldwide volume. e.g. 2840 |

One of these sets must be complete (anything else is `invalid_input`, ₹0): `keywords`.

## What drives the cost

Nothing you can turn, which is the point: the price is flat per call for up to 1,000 keywords. One keyword and a thousand cost the same, so batch every keyword you have into one call; one keyword per call is the dearest way to use it. `date_from` and `date_to` (yyyy-mm-dd) choose the months; the default is the last twelve.

## Price today

| | |
|---|---|
| Price today | **₹10** per call (`cost_paise: 1015`) at ₹93.93 per US dollar on 17 November 2026 |
| Hold before the call | ₹15.23 (`hold_paise: 1523`); when the call settles the real price is charged and the unused part is released |
| ₹0 when | it fails, or the provider answers but there is nothing in it (an empty list, no email, no page): `class: "ok_free"`, ₹0 |
| Timeout | 30 s, then `upstream_timeout` (₹0, retryable) |
| Over MCP | `run_tool` with `tool: "keyword_volume"` |
| Over REST | `POST https://api.parel.si/v1/run` with `"tool": "keyword_volume"` |
| Confirmation | not needed (the estimate is under the ₹200 threshold) |

## Request

```bash
curl https://api.parel.si/v1/run \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"keyword_volume","input":{"keywords":["protein bar","whey protein","peanut butter"],"language_code":"en","location_code":2356}}'
```

## What comes back

`data[]`, one row per keyword that has data. A real answer recorded during the live check of 2026-10-28 (two keywords sent), trimmed to two months per keyword:

```json
[
  {
    "keyword": "protein bar",
    "spell": null,
    "location_code": 2356,
    "language_code": "en",
    "search_partners": false,
    "competition": "HIGH",
    "competition_index": 96,
    "search_volume": 110000,
    "low_top_of_page_bid": 0.01,
    "high_top_of_page_bid": 0.33,
    "cpc": 0.06,
    "monthly_searches": [
      {
        "year": 2026,
        "month": 9,
        "search_volume": 135000
      },
      {
        "year": 2026,
        "month": 8,
        "search_volume": 135000
      },
      "… 10 more item(s) truncated"
    ]
  },
  {
    "keyword": "whey protein",
    "spell": null,
    "location_code": 2356,
    "language_code": "en",
    "search_partners": false,
    "competition": "HIGH",
    "competition_index": 100,
    "search_volume": 368000,
    "low_top_of_page_bid": 0.04,
    "high_top_of_page_bid": 0.36,
    "cpc": 0.21,
    "monthly_searches": [
      {
        "year": 2026,
        "month": 9,
        "search_volume": 550000
      },
      {
        "year": 2026,
        "month": 8,
        "search_volume": 550000
      },
      "… 10 more item(s) truncated"
    ]
  }
]
```

## Notes

- Flat price per call however many keywords (up to 1,000): batch them. One keyword per call is the dearest way to use it.
- Volumes are Google Ads averages, rounded; a keyword with no data is simply missing from data[].
- India: location_code 2356 (language_code "en" or "hi"); 2840 is the United States; no location means worldwide.
- date_from and date_to (yyyy-mm-dd) pick the months; the default is the last twelve.

## Siblings

- [`keyword_data`](https://parel.si/docs/tools/keyword_data.md) for the trend.
- [`rank_check`](https://parel.si/docs/tools/rank_check.md) for the ranking.
