# Dfs Google Ads Search Volume

> Fetch Google Ads search volume data using DataForSEO API with automatic batching for large keyword lists. Returns search volumes, competition metrics, CPC data, and 24-month historical trends. Use when needing Google Ads metrics for PPC planning, keyword research, competitive analysis, or any task requiring search demand with advertising insights. Automatically batches requests in groups of 1000 keywords with rate limiting.

- Skill: `buzzmatic/dfs-google-ads-search-volume` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/dfs-google-ads-search-volume`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/dfs-google-ads-search-volume/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/dfs-google-ads-search-volume

---


# DataForSEO Google Ads Search Volume

Fetches Google Ads search volume data with automatic batching support for unlimited keywords.

## Quick Start

Fetch search volume for keywords (comma-separated):

```bash
python scripts/fetch.py --keywords "seo tools,ppc advertising,google ads" --location 2840
```

Fetch from file with automatic batching (recommended for large lists):

```bash
python scripts/fetch.py --keywords-file keywords.txt --location-name "United States"
```

## Automatic Batching

**The script automatically handles large keyword lists:**
- Splits keywords into batches of 1000 (API limit)
- Adds 5-second delay between batches (rate limiting: 12 requests/minute)
- Combines all results into single output file
- Reports progress and per-batch costs

**Example:** A file with 3,500 keywords will be processed in 4 batches automatically.

## Script Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--keywords` | * | - | Comma-separated keywords |
| `--keywords-file` | * | - | Path to file with keywords (one per line) |
| `--location` | No | Global | Location code (e.g., 2840 for United States) |
| `--location-name` | No | Global | Location name (e.g., "United States") |
| `--language` | No | - | Language code (e.g., en, de) |
| `--language-name` | No | - | Language name (e.g., "English") |
| `--search-partners` | No | false | Include Google search partner networks |
| `--date-from` | No | - | Start date for historical data (YYYY-MM-DD) |
| `--date-to` | No | - | End date for historical data (YYYY-MM-DD) |
| `--include-adult` | No | false | Include adult keywords in results |
| `--sort-by` | No | - | Sort by: search_volume, competition_index, cpc, etc. |
| `--tag` | No | - | Task identifier (max 255 chars) |
| `--output` | No | auto | Custom output path |
| `--batch-size` | No | 1000 | Keywords per batch (max 1000) |

*Either `--keywords` or `--keywords-file` required.

## Common Location Codes

| Country | Code |
|---------|------|
| United States | 2840 |
| United Kingdom | 2826 |
| Germany | 2276 |
| France | 2250 |
| Spain | 2724 |
| Italy | 2380 |
| Canada | 2124 |
| Australia | 2036 |
| Austria | 2040 |
| Switzerland | 2756 |

## Examples

**Basic usage with small keyword list:**
```bash
python scripts/fetch.py \
  --keywords "running shoes,nike shoes,adidas shoes" \
  --location 2840
```

**Large keyword list with automatic batching:**
```bash
python scripts/fetch.py \
  --keywords-file keywords_5000.txt \
  --location-name "United States" \
  --language en
```

**Include search partners for broader reach:**
```bash
python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2840 \
  --search-partners
```

**Historical data range (up to 24 months):**
```bash
python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2840 \
  --date-from "2024-01-01" \
  --date-to "2024-12-31"
```

**Sort results by CPC for PPC planning:**
```bash
python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2840 \
  --sort-by "cpc"
```

**German keywords with custom output path:**
```bash
python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2276 \
  --language de \
  --output output/de_search_volume.json
```

**Custom batch size (smaller batches for testing):**
```bash
python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2840 \
  --batch-size 500
```

## Keywords File Format

Create a text file with one keyword per line:

```
seo tools
keyword research
google ads ppc
pay per click advertising
search engine marketing
```

**Keyword constraints:**
- Maximum 80 characters per keyword
- Maximum 10 words per phrase
- Keywords automatically converted to lowercase by API

## Output

Returns JSON with combined results from all batches containing:

| Field | Description |
|-------|-------------|
| `keyword` | The keyword (as processed by API) |
| `spell` | Corrected spelling if applicable |
| `search_volume` | Average monthly search volume |
| `competition` | Competition level (LOW, MEDIUM, HIGH) |
| `competition_index` | Competition index (0-100) |
| `low_top_of_page_bid` | Low bid estimate for top of page |
| `high_top_of_page_bid` | High bid estimate for top of page |
| `cpc` | Cost per click estimate |
| `monthly_searches` | Array of historical monthly data (up to 24 months) |

**Output structure:**
```json
{
  "status_code": 20000,
  "cost": 0.15,
  "result_count": 3500,
  "metadata": {
    "total_keywords": 3500,
    "location": "United States",
    "fetched_at": "2025-01-04T10:30:00"
  },
  "results": [
    {
      "keyword": "seo tools",
      "search_volume": 14800,
      "competition": "HIGH",
      "competition_index": 87,
      "cpc": 12.45,
      "low_top_of_page_bid": 8.20,
      "high_top_of_page_bid": 18.50,
      "monthly_searches": [...]
    }
  ]
}
```

## Use Cases

### PPC Campaign Planning
Assess keyword costs and competition before launching campaigns:

```bash
python scripts/fetch.py \
  --keywords-file campaign_keywords.txt \
  --location 2840 \
  --search-partners \
  --sort-by "cpc"
```

### Keyword Research with Advertising Insights
Identify high-volume, low-competition opportunities:

```bash
python scripts/fetch.py \
  --keywords-file seed_keywords.txt \
  --location-name "Germany" \
  --language de
```

### Budget Forecasting
Estimate PPC costs using CPC and volume data:

```bash
python scripts/fetch.py \
  --keywords-file target_keywords.txt \
  --location 2840 \
  --date-from "2024-01-01" \
  --date-to "2024-12-31"
```

### Competitive Analysis
Compare keyword metrics across competitor terms:

```bash
python scripts/fetch.py \
  --keywords "brand a,brand b,competitor brand,our brand" \
  --location 2840 \
  --search-partners
```

### Seasonal Trend Analysis
Analyze 24-month historical patterns for seasonal campaigns:

```bash
python scripts/fetch.py \
  --keywords-file seasonal_products.txt \
  --location 2840 \
  --date-from "2023-01-01"
```

## Batching Details

**How batching works:**
1. Script reads all keywords from file or parameter
2. Splits into chunks of 1000 (or custom batch-size)
3. Processes each batch sequentially with API call
4. Waits 5 seconds between batches (rate limit compliance)
5. Combines all results into single output file
6. Reports total cost across all batches

**Rate limiting:**
- Google Ads endpoints: 12 requests per minute maximum
- Script enforces 5-second delay = ~12 requests/minute
- Large lists (10,000+ keywords) will take proportional time

**Cost efficiency:**
- Each batch (up to 1000 keywords) = 1 API request
- More cost-efficient than individual keyword requests
- Total cost displayed after completion

## API Limits

| Limit | Value |
|-------|-------|
| Max keywords per request | 1000 |
| Max keyword length | 80 characters |
| Max words per keyword | 10 |
| Rate limit (Google Ads) | 12 requests/minute |
| Historical data range | Up to 24 months |
| Concurrent requests | 30 max (total across all endpoints) |

## Pricing Notes

- Charged per API request (not per keyword)
- Each batch (up to 1000 keywords) = 1 billable request
- Batching large lists is highly cost-efficient
- Cost displayed after each batch and total at completion
- Historical date ranges may incur additional charges

## Comparison: Google Ads vs Clickstream Data

| Feature | Google Ads (this skill) | Clickstream |
|---------|------------------------|-------------|
| **Data source** | Google Ads Keyword Planner | Clickstream behavior data |
| **Metrics** | Volume, CPC, competition, bids | Volume only |
| **Use case** | PPC planning, advertising | Organic search trends |
| **Competition data** | ✓ Yes (index 0-100) | ✗ No |
| **CPC estimates** | ✓ Yes | ✗ No |
| **Historical range** | Up to 24 months | Up to 12 months |
| **Search partners** | ✓ Configurable | ✗ N/A |
| **Rate limit** | 12/minute | 2000/minute |

**When to use Google Ads skill:**
- PPC campaign planning and budgeting
- Need competition metrics
- Require CPC/bid estimates
- Analyzing paid search opportunities

**When to use Clickstream skill:**
- Organic search volume only needed
- Faster bulk processing (higher rate limit)
- No advertising metrics required

## Environment Variables

Requires in `.env`:
```
DATAFORSEO_LOGIN=your_login
DATAFORSEO_PASSWORD=your_password
```

The script automatically loads credentials from:
1. Project root `.env` (4 directories up from script)
2. Current working directory `.env`

## Troubleshooting

**"Batch size exceeds 1000 keywords":**
- Internal error; should auto-batch correctly
- Check --batch-size parameter (must be ≤1000)

**"Keyword exceeds 80 characters":**
- Shorten keywords to max 80 characters
- API will reject or truncate longer keywords

**"Keyword has more than 10 words":**
- Reduce keyword phrase to max 10 words
- API may reject overly long phrases

**"HTTP Error 429" (Too Many Requests):**
- Rate limit exceeded
- Script automatically enforces delays
- If persistent, increase RATE_LIMIT_DELAY in script

**"HTTP Error 401":**
- Check DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD in .env
- Verify credentials are correct

**"No results returned from any batch":**
- Check API credentials
- Verify location/language codes are valid
- Ensure keywords meet API requirements

**Slow processing for large lists:**
- Expected behavior due to rate limiting
- 10,000 keywords ≈ 10 batches ≈ 50 seconds minimum
- Consider running during off-hours for very large lists

**High costs for large lists:**
- Each batch of up to 1000 keywords = 1 request charge
- Review DataForSEO pricing before processing 10,000+ keywords
- Consider testing with smaller sample first