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):

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

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

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

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

Common Location Codes

Examples

Basic usage with small keyword list:

python scripts/fetch.py \
  --keywords "running shoes,nike shoes,adidas shoes" \
  --location 2840

Large keyword list with automatic batching:

python scripts/fetch.py \
  --keywords-file keywords_5000.txt \
  --location-name "United States" \
  --language en

Include search partners for broader reach:

python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2840 \
  --search-partners

Historical data range (up to 24 months):

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:

python scripts/fetch.py \
  --keywords-file keywords.txt \
  --location 2840 \
  --sort-by "cpc"

German keywords with custom output path:

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):

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:

Output structure:

{
  "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:

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:

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

Budget Forecasting

Estimate PPC costs using CPC and volume data:

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:

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:

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

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

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