# Keyword Search Volume & CPC — Google Ads Data (BYO key) (`lizaraco/keyword-metrics`) Actor

Real Google keyword metrics — monthly search volume, CPC, competition, and 12-month trend — normalized for SEO tools and AI agents. Bring your own DataForSEO key: you pay wholesale for raw data, we charge only a tiny convenience fee. Pairs with our Google Trends actor.

- **URL**: https://apify.com/lizaraco/keyword-metrics.md
- **Developed by:** [Shawn Downs](https://apify.com/lizaraco) (community)
- **Categories:** SEO tools, AI, Automation
- **Stats:** 4 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 keywords

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/platform/actors/running/actors-in-store#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 Search Volume & CPC — Google Ads Data (bring your own key)

Get **real Google keyword metrics** — monthly search volume, cost-per-click, competition,
and a 12-month trend — in one clean, agent-ready call. Built for SEO tooling, content
planning, and AI agents doing keyword research. Pairs naturally with our
[Google Trends actor](https://apify.com/lizaraco/scrape-google-trends) (trend *shape* →
this actor's hard *numbers*).

### Bring your own key — you control the cost

This actor is **bring-your-own-key**: you supply your own [DataForSEO](https://dataforseo.com)
login, and **you pay DataForSEO directly** for the raw data at their wholesale rates. This
actor never uses anyone else's key and never marks up your data cost — you're only charged a
tiny per-result convenience fee for the normalization and agent-ready output.

- **Free to test:** flip on `useSandbox` to hit DataForSEO's sandbox (sample data, no charge
  to your balance) and confirm your wiring before spending a cent.
- **Legitimate data:** DataForSEO licenses Google Ads keyword data — no Keyword Planner
  scraping, no Ads-login ToS violations, nothing that breaks next week.

### Modes

- **`volume`** — pass exact keywords, get search volume / CPC / competition / trend for each.
- **`suggestions`** — pass seed keywords, get related keywords (each with its own metrics),
  capped by `maxSuggestions` per seed.

### Output (per keyword)

`keyword, search_volume, cpc, competition, competition_index, low_top_bid, high_top_bid,
monthly_trend[{ym, volume}], location, language` (suggestions mode adds `seed`).

### Setup

1. Create a DataForSEO account (free sandbox available).
2. Put your login in `dataForSeoLogin` and API password in `dataForSeoPassword` (stored
   encrypted).
3. Set `location` / `language` (defaults: United States / English) and run.

Missing or invalid credentials never crash the run — you get a clear note back and nothing
is charged.

### Pricing

Pay per keyword returned (`volume`) or per seed expanded (`suggestions`) — pay-per-event.
Your DataForSEO data cost is separate and billed by them.

# Actor input Schema

## `mode` (type: `string`):

volume: metrics for the exact keywords you pass. suggestions: expand each keyword into related keywords with their own metrics.

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

In 'volume' mode: the exact keywords to look up. In 'suggestions' mode: seed keywords to expand.

## `dataForSeoLogin` (type: `string`):

Your DataForSEO account login. You pay DataForSEO directly for raw data — this actor never uses our key. Get one free (sandbox) at dataforseo.com.

## `dataForSeoPassword` (type: `string`):

Your DataForSEO API password — OR the 'Base64 Format' token from DataForSEO's API Access page (the value with the copy button). Either one works. Stored encrypted.

## `location` (type: `string`):

Location name (e.g. 'United States', 'United Kingdom', 'Canada').

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

Language name (e.g. 'English', 'Spanish').

## `maxSuggestions` (type: `integer`):

Suggestions mode only: cap related keywords returned per seed.

## `useSandbox` (type: `boolean`):

Route to DataForSEO's free sandbox (sample data, no charge to your DataForSEO balance) to test wiring before spending.

## Actor input object example

```json
{
  "mode": "volume",
  "keywords": [
    "running shoes",
    "trail running shoes"
  ],
  "location": "United States",
  "language": "English",
  "maxSuggestions": 100,
  "useSandbox": false
}
```

# 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",
        "trail running shoes"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("lizaraco/keyword-metrics").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",
        "trail running shoes",
    ] }

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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",
    "trail running shoes"
  ]
}' |
apify call lizaraco/keyword-metrics --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=lizaraco/keyword-metrics",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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