google-ads-keyword-planner

Files (25)

• .gitignore
• README-keyword-planner.md
• SKILL.md
• .env.example · config/
• README.md · config/
• google-ads.yaml.example · config/
• MISSED_DEMAND.md · references/
• common.ps1 · scripts/
• dynamics.ps1 · scripts/
• generate_keyword_ideas.ps1 · scripts/
• geo_lookup.ps1 · scripts/
• geo_targets.ps1 · scripts/
• get_token.ps1 · scripts/
• health_check.cmd · scripts/
• health_check.ps1 · scripts/
• historical_metrics.ps1 · scripts/
• keyword_ideas.ps1 · scripts/
• missed_demand.py · scripts/
• query_total.ps1 · scripts/
• quota.ps1 · scripts/
• regions_stats.ps1 · scripts/
• regions_tree.ps1 · scripts/
• search_region.ps1 · scripts/
• search_volume.ps1 · scripts/
• top_requests.ps1 · scripts/

SKILL.md (first lines)

# google-ads-keyword-planner

Keyword demand analysis inside Google Ads scope.

## Scope

- Uses official Google Ads API only (REST).
- Works with ad-account data and keyword planning endpoints.
- Does NOT parse organic Google SERP.
- For organic Google SERP analysis, use external tools (SerpAPI, ScaleSerp, etc.).

## Using seos-cli in this skill

Adoption decision: use `seos-cli` for standard project-native keyword reports, and keep this skill's copied Google Ads scripts for low-level Google Ads API operations that the CLI does not expose.

Use `seos-cli` when the task needs repeatable exports, checkpointed project workflow, or combined Ads/SERP/Trends enrichment:

```powershell
seos-cli config check
seos-cli ads --keywords "seed keyword, second seed" --format xlsx --out outputs/google-ads-keyword-plan.xlsx
seos-cli run --keywords "seed keyword" --steps ads,serp,trends,merge,export --format xlsx --out outputs/keyword-plan-enriched.xlsx
```

Inputs: comma-separated seed keywords, or `--from-file` with one keyword per line. Output: XLSX/CSV/JSON report at the explicit `--out` path.

Do not use `seos-cli` for geo-target lookup, token refresh, raw Google Ads troubleshooting, or missed-demand OR-query utilities unless the CLI grows those capabilities later. Do not copy secrets into this skill folder; check project credentials through `seos-cli config check` and keep API keys out of reports.

## Required 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.
- Alternative: `config/google-ads.yaml` for Python SDK (see `config/google-ads.yaml.example`).

## Philosophy

1. **Skepticism to non-target demand** — high search volume doesn't mean quality traffic
2. **Creative semantic expansion** — think like a customer, not a marketer
3. **Always clarify region** — ask user for target geo before analysis
4. **Show data in reports** — include competition, bids, and monthly trends for verification
5. **VERIFY INTENT via web search** — always check what people actually want to buy

## CRITICAL: Intent Verification

**Before marking ANY query as "target", verify intent via WebSearch!**

### The Problem

Query "каолиновая вата для дымохода" looks relevant for chimney seller, but:

- People search this to BUY COTTON WOOL, not chimneys
- They already HAVE a chimney and need insulation material
- This is NOT a target query for chimney sales!

### Verification Process

For every promising query, ASK YOURSELF:

1. **What does the person want to BUY?** (not just "what are they interested in")
2. **Will they buy OUR product from this search?**
3. **Or are they looking for something adjacent/complementary?**

### MANDATORY: Use WebSearch

**Always run WebSearch** to check:

```text
WebSearch: "каолиновая вата для дымохода" что ищут покупатели
```

Look at search results:

- What products are shown?
- What questions do people ask?
- Is this informational or transactional intent?

### Red Flags (likely NOT target)

- Query contains "для [вашего продукта]" — they need ACCESSORY, not your product
- Query about materials/components — they DIY, not buy finished product
- Query has "своими руками", "how to make" — informational, not buying
- Query about repair/maintenance — they already own it

### Examples

| Query                         | Looks like     | Actually           | Target? |
|-------------------------------|----------------|--------------------|---------|
| каолиновая вата для дымохода  | chimney buyer  | cotton wool buyer  | ❌ NO   |
| дымоход купить                | chimney buyer  | chimney buyer      | ✅ YES  |
| утепление дымохода            | chimney buyer  | insulation DIYer   | ❌ NO   |
| дымоход сэндвич цена          | chimney buyer  | chimney buyer      | ✅ YES  |
| потерпевший дтп               | lawyer client  | news reader        | ❌ NO   |
| юрист после дтп                | lawyer client  | lawyer client      | ✅ YES  |

## Workflow

### STOP! Before any analysis

1. **ASK user about region and WAIT for answer:**

   ```text
   "For which region should I analyze the demand?
   - Worldwide / specific country?
   - Specific city (which one?)"
   ```

   **DO NOT CONTINUE until the user answers!**

2. **ASK about business goal:**

   ```text
   "What exactly are you selling/promoting?
   This is important to filter out non-target queries."
   ```

### After getting answers

1. **Find geo target ID:**

```bash

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

More from skargaklop/seo-keyword-public