# Keyword Volume Checker (`problemsolver/keyword-volume-checker`) Actor

Looks up real Google Ads historical search volume, competition, CPC bid ranges and 12-month trend for a ready-made list of keywords using the official Google Ads API (KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics).

- **URL**: https://apify.com/problemsolver/keyword-volume-checker.md
- **Developed by:** [Dimitris Kouretas](https://apify.com/problemsolver) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 keyword metrics returneds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Keyword Volume Checker

Get real Google Ads search volume, competition, CPC bid ranges and a 12-month trend for a keyword list you already have — no idea generation, no seed keywords. Give it the exact keywords you want checked and it returns real Google Ads Keyword Planner data for the country and language you target.

### What makes this different

Most keyword volume tools show estimated or modeled search volume, often scraped from search results or inferred from third-party click data. This Actor calls Google's own `KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics` endpoint — the exact API behind Google Ads Keyword Planner's historical metrics. Average monthly searches, month-by-month search volume for the past 12 months, competition level, competition index, and CPC bid ranges are Google's first-party numbers, not an approximation.

This Actor checks the exact keywords you give it. If you're looking for new keyword *ideas* from a seed term instead, see our [Google Keyword Planner Tool](https://apify.com/problemsolver/google-keyword-planner-tool).

### Input

Example input:

```json
{
  "keywords": ["seo tools", "keyword research", "backlink checker"],
  "country": "GR",
  "language": "en"
}
```

| Field | Description |
|---|---|
| `keywords` | Your ready-made list of keywords to look up (not seed keywords — you get data back for exactly the keywords you provide, though Google Ads may merge near-exact variants like plurals into a single row). |
| `country` | Country to target, selected from a dropdown (e.g. Greece, United States, Germany). Mapped internally to the matching Google Ads geo-target-constant. |
| `language` | Language to target, selected from a dropdown (e.g. English, German, Greek). Mapped internally to the matching Google Ads language-constant. |
| `includeAdultKeywords` | Optional. Include adult keywords in the results. Off by default. |

No Google Ads account or API setup needed on your side — see the FAQ below.

### Output

One dataset item per keyword. Example:

```json
{
  "keyword": "seo tools",
  "closeVariants": null,
  "avgMonthlySearches": "1600",
  "competition": "LOW",
  "competitionIndex": "1",
  "lowTopOfPageBid": 0.659741,
  "highTopOfPageBid": 2.324669,
  "averageCpc": 1.12,
  "monthlySearchVolumes": [
    { "year": 2025, "month": "SEPTEMBER", "searches": 1300 },
    { "year": 2025, "month": "OCTOBER", "searches": 1400 }
  ],
  "trend": "rising"
}
```

| Field | Description |
|---|---|
| `keyword` | The keyword text returned by Google Ads. |
| `closeVariants` | Other keywords from your input list that Google Ads merged into this row as near-exact variants (e.g. "car" absorbing "cars"). `null` if none were merged. |
| `avgMonthlySearches` | Average monthly search volume for this keyword over the past 12 months. |
| `competition` | Google's competition rating: `LOW`, `MEDIUM`, or `HIGH`. |
| `competitionIndex` | Numeric competition score (0–100). `null` if not enough data is available. |
| `lowTopOfPageBid` / `highTopOfPageBid` | Google's estimated top-of-page CPC bid range (20th/80th percentile), in EUR. |
| `averageCpc` | Average cost-per-click for this keyword, in EUR. |
| `monthlySearchVolumes` | Search volume broken down by month for the past 12 months. A `null` `searches` value means volume was unavailable for that month. |
| `trend` | `"rising"`, `"stable"` or `"declining"` — compares the average of the last 3 months against the previous 3 months (≥15% difference either way). `null` if there isn't enough monthly data to compute it. |

### Pricing

This Actor uses pay-per-event pricing:

- **$0.002 per keyword** returned and written to the dataset.

You're only charged for keywords that are actually written to the dataset — nothing is billed for a run that fails before returning results. Note that Google Ads may merge near-exact variants of your input keywords into a single row (see `closeVariants` above), so the number of dataset rows can be slightly lower than the number of keywords you submitted.

We recommend setting a "Maximum cost per run" limit in the Run options before your first run with a very large keyword list if you want to control costs.

This Actor shares Google Ads API access across all users; if you run it during a busy moment, a request may retry automatically and take a few extra seconds — results are unaffected.

### Try it instantly

Want to see it in action before running it yourself? Check out this ready-to-run example with pre-filled keywords:

https://apify.com/problemsolver/keyword-volume-checker/examples/keyword-volume-checker-task

### Found this useful?

If this Actor saved you time, a quick review helps other users discover it. Thanks for trying it out!

### Use cases

- **SEO research** — check real search volume and trend direction before committing content resources to a keyword list.
- **PPC campaign planning** — get real CPC bid ranges for keywords you've already selected.
- **Content refresh prioritization** — spot keywords with a declining trend before traffic drops.
- **Keyword list validation** — confirm the real Google Ads numbers behind a keyword list from another tool or client.

### FAQ

**Do I need my own Google Ads account?**
No setup required on your side. Just provide keywords, country, and language — we handle the Google Ads API access behind the scenes.

**What countries and languages are supported?**
21 countries — including the United States, United Kingdom, Germany, France, Spain, Italy, and Greece — and 19 languages, including English, German, French, Spanish, Italian, and Greek. Both are selected from dropdowns in the input; no need to know Google's internal geo-target or language-constant IDs.

**How far back does the historical data go?**
The past 12 months, month by month, plus the 12-month average.

**Why did I get fewer rows than keywords I submitted?**
Google Ads merges near-exact variants (e.g. singular/plural forms) into a single row before returning results. See the `closeVariants` field on the merged row.

**What currency are the CPC bid values in?**
Note: CPC bid values are returned in the currency of the Google Ads account behind this Actor (EUR), not USD.

# Actor input Schema

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

Your ready-made list of keywords to look up (not seed keywords for idea generation — use exactly the keywords you provide).

## `country` (type: `string`):

Country to target. Internally mapped to the correct Google Ads geo-target-constant ID.

## `language` (type: `string`):

Language to target. Internally mapped to the correct Google Ads language-constant ID.

## `includeAdultKeywords` (type: `boolean`):

Whether to include adult keywords in the results. Off by default, matching the Google Ads API default.

## Actor input object example

```json
{
  "keywords": [
    "seo tools",
    "keyword research"
  ],
  "country": "GR",
  "language": "en",
  "includeAdultKeywords": false
}
```

# Actor output Schema

## `keywordMetrics` (type: `string`):

The dataset of this run, one row per keyword.

# 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": [
        "seo tools",
        "keyword research"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("problemsolver/keyword-volume-checker").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": [
        "seo tools",
        "keyword research",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("problemsolver/keyword-volume-checker").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": [
    "seo tools",
    "keyword research"
  ]
}' |
apify call problemsolver/keyword-volume-checker --silent --output-dataset

```

## MCP server setup

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

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/FYLLz5GlR80Ime36i/builds/6mECMhvZLUSmLYx4z/openapi.json