google-ads-search-terms

Files (17)

• .gitignore
• README-search-terms.md
• SKILL.md
• .env.example · config/
• README.md · config/
• config.example.json · config/
• auth_check.cmd · scripts/
• auth_check.ps1 · scripts/
• common.ps1 · scripts/
• geo_lookup.ps1 · scripts/
• iam_token_get.ps1 · scripts/
• regions_tree.ps1 · scripts/
• search_region.ps1 · scripts/
• search_terms_batch.ps1 · scripts/
• search_terms_sync.ps1 · scripts/
• web_search_async.ps1 · scripts/
• web_search_sync.ps1 · scripts/

SKILL.md (first lines)

# google-ads-search-terms

Analyze paid search terms from Google Ads account data.

## Scope

- Uses GAQL `search_term_view` via Google Ads API (REST).
- Supports sync query mode and batch mode with resume cache.
- Does **NOT** fetch organic Google SERP.
- Analyzes **search queries from your ad account** — real terms that triggered your ads.

## Using seos-cli in this skill

Adoption decision: `seos-cli` is optional. Use this skill's copied GAQL scripts to export real Google Ads search terms. Use `seos-cli` only after terms are exported or otherwise prepared as one term per line and the task needs downstream project enrichment.

Useful enrichment command:

```powershell
seos-cli config check
seos-cli run --from-file search_terms.txt --steps ads,serp,trends,merge,export --format xlsx --out outputs/search-terms-enriched.xlsx
```

Input requirement: `search_terms.txt` must be UTF-8 text with one search term per line. `seos-cli` does not directly parse arbitrary Google Ads search-term CSV schemas in this adoption pass.

Do not use `seos-cli` for the primary search-term export, campaign/date filtering, GAQL troubleshooting, or batch resume. Those remain owned by this skill's scripts until a direct CSV ingestion feature is implemented.

## Config

Prefer the project-level Google Ads configuration verified by `seos-cli config check`.
Standalone copied scripts can still read `config/.env` for local debugging, but do not store real credentials in the copied skill package or commit them.

## Workflow

### STOP! Before any analysis

1. **ASK user about date range:**

   ```text
   "For what period should I export search queries?
   - Last 30 days (default)
   - Specific range (which one?)"
   ```

2. **ASK about campaign scope:**

   ```text
   "All campaigns or specific ones?
   If specific — please provide IDs or names."
   ```

### After getting answers

1. Auth/access check:

```bash
bash scripts/auth_check.sh
# Windows
.\scripts\auth_check.ps1
```

1. Find geo targets (if needed):

```bash
bash scripts/geo_lookup.sh --query "Moscow" --country-code RU
# Windows
.\scripts\geo_lookup.ps1 -Query "Moscow" -CountryCode RU
```

1. Sync export:

```bash
bash scripts/search_terms_sync.sh \
  --date-from 2026-01-01 --date-to 2026-01-31 \
  --min-impressions 10 --limit 1000 --csv export.csv
# Windows
.\scripts\search_terms_sync.ps1 -DateFrom 2026-01-01 -DateTo 2026-01-31 `
  -MinImpressions 10 -Limit 1000 -Csv export.csv
```

1. Batch by date chunks with all campaigns:

```bash
bash scripts/search_terms_batch.sh \
  --date-from 2026-01-01 --date-to 2026-02-15 \
  --step-days 7 --all-campaigns --csv full_export.csv
# Windows
.\scripts\search_terms_batch.ps1 -DateFrom 2026-01-01 -DateTo 2026-02-15 `
  -StepDays 7 -AllCampaigns -Csv full_export.csv
```

1. Batch by specific campaigns:

```bash
bash scripts/search_terms_batch.sh \
  --date-from 2026-01-01 --date-to 2026-02-15 \
  --step-days 7 --campaign-ids 111,222
# Windows
.\scripts\search_terms_batch.ps1 -DateFrom 2026-01-01 -DateTo 2026-02-15 `
  -StepDays 7 -CampaignIds 111,222
```

1. Resume unfinished batch:

```bash
bash scripts/search_terms_batch.sh --resume --csv export.csv
# Windows
.\scripts\search_terms_batch.ps1 -Resume -Csv export.csv
```

## Scripts

Each script has a Bash (`.sh`) and PowerShell (`.ps1`) version.

### Bash (Linux/macOS)

- `scripts/common.sh` — shared OAuth/token/API helpers.
- `scripts/auth_check.sh` — auth and API smoke check.
- `scripts/search_terms_sync.sh` — one GAQL export call.
- `scripts/search_terms_batch.sh` — chunked execution with cache/resume.

From skargaklop/seo-keyword-public, AGPL-3.0.

More from skargaklop/seo-keyword-public