# Keyword Search Volume & CPC: Google Ads Keyword Planner Data (`datagleaner/keyword-volume`) Actor

Keyword search volume API: monthly Google searches, CPC, competition and 12-month history for up to 10,000 keywords per run, from Google Ads data. Any country and language. $0.0008 per keyword with data plus $0.02 per 700-keyword batch; no-data keywords are free.

- **URL**: https://apify.com/datagleaner/keyword-volume.md
- **Developed by:** [Data Gleaner](https://apify.com/datagleaner) (community)
- **Categories:** SEO tools, Marketing, Automation
- **Security:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 1,000 keyword with data

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Keyword Search Volume & CPC: Google Ads Keyword Planner data for up to 10,000 keywords

**Monthly Google search volume, CPC, advertiser competition and the 12-month history for every keyword on your list, from Google Ads Keyword Planner data.** Paste keywords, pick a country and a language, and get one clean row per keyword as JSON, CSV or Excel. No Google Ads account, no API key, no login. **$0.0008 per keyword with data plus $0.02 per batch of up to 700 keywords: 50 keywords cost $0.06, 1,000 cost $0.84. Keywords with no data are free.**

#### Why this one

- **Real Keyword Planner numbers.** Search volume, CPC, top-of-page bid range and competition come from the Google Ads keyword data, not from a guess or a scrape of suggestions.
- **Cheap at scale.** 10,000 keywords cost $8.30. Keywords Google has no volume for, and keywords that are invalid, come back as free rows with the reason, so you pay only for rows with data.
- **Any country, any language.** Pick a country by name, or use a Google Ads location code for any country, region or city.
- **12-month history.** Every row can carry the last 12 months of searches, so you can see seasonality and trend, not just an average.
- **Built for pipelines and AI agents.** Flat rows, stable camelCase fields, numbers as numbers, a run summary in the status message.

#### Minimal input

```json
{"keywords": ["running shoes", "wireless earbuds", "standing desk"], "locationName": "United States", "languageCode": "en"}
```

An empty input runs a built-in example with 3 keywords.

#### Sample output

| keyword | searchVolume | cpc | competition | competitionIndex | lowTopOfPageBid | highTopOfPageBid |
|---|---|---|---|---|---|---|
| running shoes | 823000 | 1.10 | HIGH | 97 | 0.45 | 1.62 |
| yoga mat | 301000 | 0.71 | MEDIUM | 58 | 0.30 | 0.98 |
| standing desk | 135000 | 1.84 | HIGH | 89 | 0.62 | 2.47 |

One row as JSON:

```json
{
  "keyword": "yoga mat",
  "searchVolume": 301000,
  "cpc": 0.71,
  "competition": "MEDIUM",
  "competitionIndex": 58,
  "lowTopOfPageBid": 0.3,
  "highTopOfPageBid": 0.98,
  "monthlySearches": [
    {"year": 2026, "month": 9, "searchVolume": 301000},
    {"year": 2026, "month": 8, "searchVolume": 246000}
  ],
  "locationCode": 2840,
  "languageCode": "en",
  "failureReason": null,
  "scrapedAt": "2026-10-25T10:00:00Z",
  "input": {"locationCode": 2840, "languageCode": "en", "searchPartners": false, "includeMonthlyHistory": true}
}
```

(The table values and `monthlySearches` above are illustrative; `monthlySearches` lists all 12 months in a real row.)

#### Price

Final prices, the same on every Apify plan:

| Event | Price | When |
|---|---|---|
| Keyword with data | $0.0008 | Each row that carries search volume |
| Keyword batch | $0.02 | Each batch of up to 700 keywords looked up in the keyword database (about 90 countries, each in its own languages) |
| Keyword Planner batch | $0.12 | Each batch of up to 1,000 keywords for a region, a city, a country and language pair outside the database, or with search partners on. Replaces the $0.02 batch fee |

Invalid keywords, keywords with no Google data and keywords not processed are free. A run whose lookup fails is not charged.

| Run | Keywords | Cost |
|---|---|---|
| One keyword check | 1 | $0.0208 |
| Check a content brief | 50 | $0.06 |
| Keyword list for one site | 1,000 | $0.84 (2 batches) |
| Full research run, the per-run maximum | 10,000 | $8.30 (15 batches) |
| 50 keywords for a city | 50 | $0.16 (Keyword Planner batch) |

Set a maximum charge per run in Apify and the run stops when it is reached; a batch is never sent that the limit cannot pay for.

### What does Keyword Search Volume & CPC do?

- Looks up your keywords in batches (700 from the keyword database, 1,000 from Keyword Planner live) and returns **average monthly searches** for the last 12 months.
- Adds **CPC**, the **top-of-page bid range** (low and high), the **competition level** (LOW, MEDIUM, HIGH) and the **competition index** (0 to 100) advertisers face.
- Adds the **monthly search history** of each keyword, on by default.
- Lowercases, trims and de-duplicates your list, and lists invalid keywords with the reason instead of failing the run.
- Works for any Google Ads location and language.

#### Use cases

- **SEO and content planning.** Rank topic ideas by demand before you write.
- **PPC budgeting.** Estimate what a keyword costs per click and how crowded it is before you bid.
- **Niche and product research.** Compare demand across hundreds of product or service terms in one run.
- **Seasonality.** Spot the months a keyword peaks from the 12-month history.
- **Local and international markets.** Run the same list per country to compare demand.
- **AI agents and pipelines.** Give an agent real demand numbers instead of letting it guess.

### Input

| Field | Type | What it does |
|---|---|---|
| `keywords` | list of text | Up to 10,000 keywords. Prefilled with 5 examples. Empty runs the built-in 3-keyword example. |
| `locationName` | text | Optional country name, such as United States (default), United Kingdom, Canada, Australia, Germany, France, Spain, Italy, Netherlands, India, Brazil, Mexico, Japan, South Korea, Taiwan, Thailand, Vietnam or Saudi Arabia. About 90 countries are built in. |
| `locationCode` | number | Optional Google Ads location code for any other country, region or city. Overrides `locationName`. |
| `languageCode` | text | Optional language code such as `en`, `es`, `fr`, `de`, `pt`, `it`, `nl`, `ja`, `zh-TW`. Empty uses the country's main language: English where the database has it, otherwise the local one (`de` for Germany, `ja` for Japan). Language names such as `German` also work. |
| `includeMonthlyHistory` | boolean | Default true. Adds `monthlySearches` to each row. |
| `searchPartners` | boolean | Default false. Also count searches on Google's search partner sites. |

Example inputs:

```json
{"keywords": ["standing desk", "ergonomic chair"], "locationName": "United Kingdom"}
{"keywords": ["zapatillas running", "botines de futbol"], "locationName": "Spain", "languageCode": "es"}
{"keywords": ["yoga mat"], "locationCode": 2840, "includeMonthlyHistory": false}
```

#### Keyword rules

A keyword can be up to 80 characters and 10 words, and cannot contain `! @ % ^ ( ) = { } ; ~ ` < > ? \ |`or a comma. Keywords are lowercased and de-duplicated; a keyword that breaks a rule is returned as a free row with`failureReason\`.

### Output fields

| Field | Meaning |
|---|---|
| `keyword` | The keyword, lowercased and trimmed |
| `searchVolume` | Average monthly Google searches over the last 12 months |
| `cpc` | Average cost per click in USD |
| `competition` | `LOW`, `MEDIUM` or `HIGH` advertiser competition |
| `competitionIndex` | Advertiser competition, 0 to 100 |
| `lowTopOfPageBid`, `highTopOfPageBid` | Range of the top-of-page bid in USD |
| `monthlySearches` | Last 12 months: `year`, `month`, `searchVolume` (when history is on) |
| `locationCode`, `languageCode` | The location and language used |
| `failureReason` | Empty for rows with data; otherwise why the row has none. Those rows are free |
| `scrapedAt`, `input` | When the row was collected and the settings that produced it |

### Limits

- Up to 10,000 distinct keywords per run. Run again for more.
- Very rare keywords often have no volume in Google's data; they come back as free rows.
- Google reports volume in rounded ranges for some keywords, and CPC is an estimate of what advertisers pay, not a promise.
- Volumes are averages of the last 12 months for the chosen location and language.
- If a run nears its time limit it stops, lists the keywords it did not reach as free rows, and ends successfully with what it has.

### FAQ

**Do I need a Google Ads account or an API key?** No. Add your keywords and run.

**Am I charged for keywords with no data?** No. Only rows with `searchVolume` are billed.

**Which country is used by default?** The United States, in English. For another country with no language set, English is used where the keyword database has it, otherwise the country's own language.

**How fresh is the data?** For about 90 countries, each in its own languages, rows come from a Google Ads keyword database refreshed every month, the same cadence at which Google updates monthly volumes. Regions, cities, other country and language pairs, and runs with search partners on, query Keyword Planner live, which costs more per batch.

**Why is there a batch fee?** The keyword data is bought per lookup batch, so a run of 1 keyword costs almost as much to serve as a run of 700. The batch fee covers that; the per-keyword price stays low for big lists.

**Can I get more than 10,000 keywords?** Split the list over several runs.

### Responsible use

This Actor returns aggregate keyword statistics, not personal data. Use it in line with the terms of the services you build on, and check the volumes and bids as estimates when you plan budgets.

# Actor input Schema

## `keywords` (type: `array`):

Keywords to look up, up to 10,000 per run. Each is lowercased, trimmed and de-duplicated. A keyword can be up to 80 characters and 10 words, and cannot contain ! @ % ^ ( ) = { } ; ~ \` < > ? \ | or a comma. Invalid keywords come back as free rows with the reason. Leave the list empty to run a built-in 3-keyword example.

## `locationName` (type: `string`):

Country name such as "United States" (default), "United Kingdom", "Canada", "Germany" or "India". About 90 countries are built in; for a region, a city or another country use Location code. Ignored when a location code is set.

## `locationCode` (type: `integer`):

Google Ads location code for any country, region or city, for example 2840 (United States, the default), 2826 (United Kingdom) or 2124 (Canada). Overrides the country name. A region, a city, or a country and language pair outside the keyword database uses Keyword Planner live, billed at the Keyword Planner batch price.

## `languageCode` (type: `string`):

Language code such as en, es, fr, de, pt, it, nl, ja or zh-TW. Leave empty for the country's main language (English where the keyword database has it, e.g. de for Germany, ja for Japan). A language the keyword database does not have for that country uses Keyword Planner live, billed at the Keyword Planner batch price.

## `includeMonthlyHistory` (type: `boolean`):

Add monthlySearches to every row: the search volume of each of the last 12 months, to see seasonality and trend.

## `searchPartners` (type: `boolean`):

Count searches on Google's search partner sites as well as Google Search itself. Off by default. Turning it on uses Keyword Planner live, billed at the Keyword Planner batch price.

## Actor input object example

```json
{
  "keywords": [
    "running shoes",
    "wireless earbuds",
    "standing desk",
    "protein powder",
    "yoga mat"
  ],
  "includeMonthlyHistory": true,
  "searchPartners": false
}
```

# Actor output Schema

## `keywords` (type: `string`):

No description

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "running shoes",
        "wireless earbuds",
        "standing desk",
        "protein powder",
        "yoga mat"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datagleaner/keyword-volume").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "keywords": [
        "running shoes",
        "wireless earbuds",
        "standing desk",
        "protein powder",
        "yoga mat",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("datagleaner/keyword-volume").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "running shoes",
    "wireless earbuds",
    "standing desk",
    "protein powder",
    "yoga mat"
  ]
}' |
apify call datagleaner/keyword-volume --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datagleaner/keyword-volume"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/avrIROoMdmYTym3wa/builds/YkiDsTKokTZS7XxHF/openapi.json