Keyword Planner

Overview

Use the local keyword-planner command to pull Google Keyword Planner ideas and search-volume metrics directly from the Google Ads API. The CLI calls Google's KeywordPlanIdeaService.GenerateKeywordIdeas, which is the API equivalent of the Keyword Planner flow in the Google Ads UI. Prefer this skill when the user asks for keyword volume, keyword ideas, demand validation, CPC/bid ranges, or a keyword list grounded in Keyword Planner rather than SERP estimates or memory.

Google does not charge a separate per-call fee for normal Google Ads API usage, but calls are governed by the developer token's access level and daily operation limits. The user still needs an eligible Google Ads account and approved API access.

Quick Start

Use JSON output by default so results can be filtered, sorted, and summarized reliably:

keyword-planner --keywords "seo tools" "keyword research" --output json

Use a URL seed when the user wants ideas from an existing page or competitor page:

keyword-planner --url "https://example.com/page" --output json

If sandbox policy requires approval for network/API access, request escalation before running the command. The command calls the Google Ads API.

Inputs

Collect or infer:

• Seed keywords with --keywords, or one seed URL with --url.
• Optional --customer-id if GOOGLE_ADS_CUSTOMER_ID is not already configured.
• Optional --location-ids; default is 2840 for the United States.
• Optional --language-id; default is 1000 for English.
• Optional existing-content spreadsheet path for exclusion.

Ask for missing seeds if the user provides neither keywords nor a URL. Do not ask for credentials unless the command fails or the user has not configured a Google Ads customer ID.

Access and Credentials

There is no simple "Keyword Planner API key." The required access credential is a Google Ads API developer token, plus authentication credentials for the Google Ads account the CLI should query.

To get access:

1. Create or choose a Google Ads manager account. The API Center is available from manager accounts, not ordinary client accounts.
2. Open the Google Ads API Center at https://ads.google.com/aw/apicenter while signed in to that manager account.
3. Complete the API Access form and accept the terms.
4. Copy the developer token shown in API Center after Google grants access. New tokens may start with Explorer or Test access before Basic or Standard access is approved.
5. Create authentication credentials for the CLI. This local wrapper is written for service-account JSON credentials, so place google-key.json where the CLI can find it or pass --key-file.
6. Set the customer ID and developer token:

GOOGLE_ADS_CUSTOMER_ID=1234567890
GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token

The CLI expects:

• Google Ads API access with service-account credentials.
• GOOGLE_ADS_CUSTOMER_ID in .env or --customer-id.
• Developer token in GOOGLE_ADS_DEVELOPER_TOKEN or as developer_token inside google-key.json.
• google-key.json, unless a different path is passed with --key-file.

If credentials fail, report the exact missing item or Google Ads API error. Do not fabricate volume, CPC, or competition data as a fallback.

Existing-Content Exclusion

By default, the CLI excludes matching ideas when outputs/lindy_titles.csv exists. This is useful for net-new content planning but can hide keywords the site already covers.

Use explicit exclusion when the user provides an inventory of existing pages:

keyword-planner --keywords "crm software" --exclude-existing-content exports/pages.csv --output json

Disable exclusion when the user wants the full Keyword Planner universe, including ideas already covered:

keyword-planner --keywords "crm software" --no-exclude-existing-content --output json

Location and Language

The defaults are United States and English. Override location when the user names a country or market:

keyword-planner --keywords "accounting software" --location-ids 2826 --language-id 1000 --output json

Common location IDs:

• 2840: United States
• 2826: United Kingdom
• 2124: Canada
• 2036: Australia

If the requested market is not one of these, look up the Google Ads geo target constant ID or ask the user for it.

Workflow

1. Decide whether the request needs live Keyword Planner data. If yes, run the CLI instead of relying on memory.
2. Use --output json unless the user explicitly asks for a table.
3. Include --no-exclude-existing-content when the user asks for all ideas or volume checks for known terms.
4. Sort and group results according to the user goal:
   • Demand validation: preserve the exact seed and closest variants first.
   • Content planning: prioritize relevant, higher-volume, lower-competition ideas.
   • Paid-search or commercial research: include competition and top-of-page bid ranges.
5. Report the filters used: seed type, location IDs, language ID, and whether existing-content exclusion was on.

Output Fields

The JSON output contains:

• keyword
• avg_monthly_searches
• competition
• competition_index
• low_top_of_page_bid_micros
• high_top_of_page_bid_micros

Convert bid micros to currency units when presenting CPC-style ranges: 1,000,000 micros equals 1.00.

Final Answer

Lead with the actionable read, not the raw dump. Include a compact table with keyword, volume, competition, and bid range when useful. Mention any failed API calls, missing credentials, unavailable markets, or filters that may have removed results.