search_term_mining v1.0.0

name: "search_term_mining" description: "Mine paid search term reports for waste and growth: export the report from Google Ads or Microsoft Advertising, sort terms by intent and conversion evidence against a target CPA, run the bundled parser for verdicts and n-gram waste patterns, promote converting queries into exact match keywords, and add negatives at the right match type and scope. Use when auditing a paid search account, cutting wasted spend, building negative keyword lists, or running the weekly search terms review."

Search Term Mining

Purpose

A keyword is what the advertiser told the platform to target. A search term is what a person actually typed. Google Ads Help defines them exactly that way, and the gap between the two lists is where paid search budgets leak and where the best new keywords hide.

This skill runs that gap as a repeatable review. Export the search terms report, judge every visible term on intent and conversion evidence against one stated benchmark, promote the queries that have earned their own keyword, negate the queries that can never buy, and roll single terms up into word patterns so a theme gets caught once instead of once per query. The bundled parser does the sorting and the pattern math. The human does the intent calls. That split is the method.

Workflow

1. Pull the right report, and say what it cannot show

• In Google Ads, go to Campaigns, then Insights and reports, then Search terms. Scope it to one campaign family at a time, turn on the Keyword column (it is not shown by default, add it under Attributes) and the Match type column, and export a window long enough for the account volume: 30 days is a workable default for an active account, 60 to 90 days for a low volume one.
• In Microsoft Advertising, go to Campaigns, then Keywords, then Search terms. Terms can be added as keywords or as negative keywords from that view, at campaign or ad group level.
• Keep these columns in the export: search term, matched keyword, campaign, ad group, match type, status (Added or Excluded), impressions, clicks, cost, conversions, and conversion value when the account tracks it.
• Write the limits at the top of the review before anyone reads a verdict. The report only shows terms used by a significant number of people that triggered impressions and clicks. Low volume terms are held back for privacy and only appear grouped in search terms insights, so visible cost is not all cost, and a theme can be real while most of its terms stay invisible. Store visits and store sales conversions are not compatible with this report in Google Ads.
• Read the Match type column correctly: it states how closely the search term relates to the keyword that matched it, and it can differ from the match type set on that keyword. A broad keyword that matched a term word for word shows as an exact relationship in the report.
• If you pull data through the Google Ads API instead, the search_term_view resource aggregates metrics by search term at ad group level and carries a status field that says whether the term is currently targeted or excluded. It does not include Performance Max data. Performance Max uses its own campaign level search term view.

2. Set the benchmark before you look at any term

• Get the target cost per conversion from the account owner, in writing, for this campaign family. A lead business and an ecommerce business judge the same term differently, and different campaign families inside one account often carry different targets.
• If there is no target, use the report average CPA as the benchmark, and label it that way in every output. An average is a description of the account, not a goal. Terms judged against it get rejudged when a real target exists.
• For revenue accounts, run the same pass on conversion value per cost instead of CPA alone when the export carries value. A term can be over target CPA and worth keeping when its orders are large. State which measure ruled each decision.
• Fix the window problem before judging: for businesses with long sales cycles, recent clicks convert late. Either exclude the most recent days from negative decisions or extend the window. Never negate on a window shorter than the normal time from click to conversion.

3. Run the bundled parser

• Run python3 bin/mine_search_terms.py report.csv --target-cpa 45 --out-md report.md --out-csv actions.csv, replacing 45 with the benchmark from step 2. Omit the flag to fall back to the report average CPA.
• The parser accepts Google Ads and Microsoft Advertising CSV exports and looser API style headers, parses money with currency symbols and commas, and understands a cost_micros column. It writes one verdict per term into the actions CSV and a summary with pattern sections into the Markdown report.
• Know the verdict rules, because you will have to defend them. Promote: at least 2 conversions at or under the benchmark. Waste candidate: zero conversions and cost at or over 2 times the benchmark. Expensive converter: at least 1 conversion at over 1.5 times the benchmark. Under-sampled: zero conversions under the waste line. These multiples are decision rules of this skill, set with the flags --promote-min-conversions, --waste-multiple, and the benchmark. They are not platform standards. Tune them with the account owner and record what you used.
• What the parser never does: apply a change to an account, negate on a theme tag alone, or judge a term it cannot benchmark. A report with zero conversions and no target CPA stops it cold, on purpose.

4. Judge intent term by term, in cost order

• Work the actions list from the highest cost down. For every term, answer one question in plain words: could this searcher ever buy what this campaign sells, at a price the business accepts? Only three answers exist: yes, no, or not proven yet.
• Sort the no answers by cause, because the cause picks the fix. Wrong product or service. Wrong geography for a local business. Job seeking. Learning or doing it themselves when the business sells the done-for-you work. Buying parts, used goods, or rentals when the business sells new or sells the service. Research with no buying signal at all.
• Use the theme tags in the actions CSV (jobs, free_seeking, diy_or_howto, used_or_rental, price_only) as reading help, never as verdicts. The worked example carries a converting term with the word "free" in it, because that business really offers a free estimate. A tag applied blind kills winners.
• Terms whose intent is right but whose numbers are bad are not negatives. An expensive converter is a bid, landing page, or offer problem. A right intent term matched by the wrong ad group is a structure problem. Fix the cause you actually found.
• Brand and competitor terms leave this workflow. Whether to bid on them, negate them, or leave them alone carries policy and legal weight that performance data cannot settle. List them in the review as their own section for the account owner.

5. Promote the queries that earned their own keyword

• A term qualifies when the parser flags it promote_exact: repeated conversions, at or under the benchmark, currently matched by a wider keyword, and not already a keyword (check the status column, the parser respects it).
• Add it as an exact match keyword in the ad group that served it, from the report itself or in the account, then do the two checks that make promotion worth anything. First, the ad copy: does an ad in that ad group speak to this term's intent in its own words, or is the searcher still reading a generic ad? Second, the landing page: does the click land on a page about this service, product, or question, not the homepage or a parent category?
• Do not pause or negate the wider keyword that found the term. The broad or phrase keyword is the discovery engine. Promotion gives the winner its own controls, it does not punish the finder.
• One conversion is not proof. A term with a single conversion stays on the watch list until the next window, whatever its CPA. Small numbers swing hard, and a keyword structure built on one conversion per term rots fast.
• Record every promotion with its before state: matched keyword, match type, conversions, and CPA in the window that earned it. That record is how the next review tells a real winner from a lucky week.

6. Negate at the right match type and the right scope

• Read references/negative-match-and-scope.md before adding anything. The core facts from Google Ads Help: negatives do not match close variants or other expansions, they do account for casing and the misspellings Google normalizes, negative broad blocks any search containing all the negative terms in any order, negative phrase blocks the terms in the same order with extra words allowed, and negative exact blocks only that exact search.
• Default to exact for a single proven waste term. It removes the proven problem and nothing else.
• Widen to phrase only when the pattern pass in step 7 shows at least three distinct terms sharing the same phrase, the same wrong intent, and zero conversions between them. Widen to broad only for a theme defined by words rather than order, after checking that no converting term in the report needs those words.
• Pick the scope by how far the wrongness travels. Ad group when the term is wrong here but wanted in a sibling ad group. Campaign when it is wrong for everything the campaign sells. A shared negative keyword list when the same waste crosses campaigns: Google allows up to 5,000 negatives per list and up to 20 lists per account, and one list edit updates every campaign using it. The account level list (up to 1,000 negatives, applied to Search and Shopping inventory in relevant campaign types) is only for terms that are wrong for the whole business.
• Organise shared lists by theme: one for job seeking, one for DIY and learning intent, one for products never sold, one for geographies never served. Themed lists can be applied and removed per campaign without surgery on single entries.
• Check for harm right after adding: a negative that blocks a live keyword cuts volume silently. In Microsoft Advertising, run the negative keyword conflicts report after campaign level phrase negatives, as its help pages direct. In Google Ads, scan the keyword list against the new negatives in the next review.

7. Run the pattern pass, because rows hide themes

• Read the n-gram sections of the parser report. It rolls every term into its one word and two word patterns and sums clicks, cost, and conversions per pattern, listing patterns carried by at least 3 distinct terms.
• A pattern with zero conversions and combined cost over the waste line is a theme candidate, even when no single term in it crossed the line alone. This is the main way mining beats manual review: forty small queries with the same wrong word are one decision, not forty.
• A pattern with conversions is protected, even when it also contains waste terms. Mixed patterns get exact negatives on the waste terms only. Never widen a negative onto a word that appears inside converting terms.
• Check the reverse direction too. A word or phrase that appears again and again inside the promoting terms is a copy and landing page signal: it is the language buyers use, and the ads and pages should use it back.
• Set --min-ngram-terms lower, to 2, for small accounts, and say so in the review. Pattern claims from 2 terms are weaker and get exact negatives only.

8. Close the review and set the next one

• Ship a change log, not a pile of edits: every keyword added with its ad group, every negative added with its match type and scope, every term deliberately left alone with the reason, and the recheck date.
• Leave under-sampled terms alone on purpose and write that down. The most common mining error after blind negation is judging a term on a window too small to hold its answer.
• Cadence, as a working rule of this skill: weekly while an account runs broad match at real spend or is in its first two months, every two weeks for stable phrase and exact accounts, and always a 30 to 90 day lookback for the pattern pass even when the weekly pass used 7 days. Low volume accounts trade frequency for window length.
• At the next review, open with the last change log. Did the negated themes stay gone, did new variants of them arrive (they will, because negatives do not expand to variants), and did promoted terms hold their CPA under their own keyword? A mining habit that never checks its own past calls is just editing.

Output Contract

A completed mining review delivers:

• The review header: account and campaign scope, date window, benchmark CPA or value measure used, where it came from, the waste and promotion rules used, and the share of spend the visible report could not itemise.
• The parser outputs: the Markdown report and the actions CSV with one verdict, one suggested action, and one reason per term.
• The promotion list: each term, its conversions and CPA, the keyword that matched it before, the ad group it joins, and the ad copy and landing page check result.
• The negative list as it will be added: term or phrase, match type, scope (ad group, campaign, named shared list, or account level), and the intent cause in one line each.
• The pattern findings: each waste theme with its combined cost and term count, each protected mixed pattern with the reason it stayed at exact negatives, and each buyer language pattern worth feeding to copy.
• The no action list: expensive converters, under-sampled terms, and brand terms, each with the reason it was left alone and what would change the call.
• The change log and the recheck date, with the first check assigned: variants of negated themes, conflicts, and promoted term performance.

The worked example in references/worked-example.md shows this contract filled in on a small invented account, and references/sample-search-terms.csv runs through the parser as shown there.

Operating Rules

• Evidence before intent, intent before action. A term is negated because its intent can never buy and its spend proves the platform keeps matching it, not because it had a bad week.
• Never invent a number this workflow depends on. No target CPA, no benchmark verdicts. No conversion value in the export, no value claims. State the fallback you used, every time.
• Zero conversions is a statement about a window, not about a term. Under the waste line, the verdict is under-sampled, and the action is patience.
• Never negate a converting term on performance grounds inside this workflow. Over target converters go to the owner as a business call, with the numbers attached.
• Exact first, widen on pattern proof only. Every widening from exact to phrase or broad names the terms that justified it.
• Positives and negatives are different machines. Negative match types do not expand to close variants the way positive matching does, so a theme is finished only when its variants have been seen and handled, usually over more than one review.
• The visible report is a sample with a privacy cut, not the whole truth. Do not present visible waste as total waste, and do not promise savings figures the hidden rows could contradict.
• Keep the account's other levers out of the change log. Mining changes keywords and negatives. Bid, budget, and page changes get proposed in the review as findings, shipped through their own process.