Demand Miner Tool

Demand Miner Tool is a private Google Ads Search campaign planning utility for the applicant's own Google Ads account. It converts campaign seed concepts into candidate Search campaign themes, ad group keyword sets, negative keyword candidates, geo/language targeting assumptions, CPC range assumptions, and local campaign build sheets for manual campaign creation in the Google Ads UI.

This project is maintained by an individual developer for internal use only. It is not an agency platform, SaaS product, public keyword database, search-results scraping tool, affiliate tool, or third-party advertising management service.

Intended Use

The tool is designed to support the planning stage before a Google Ads Search campaign is manually created.

Internal workflow:

1. Enter campaign seed concepts for the applicant's own projects.
2. Retrieve keyword ideas and historical keyword metrics from allowlisted Google Ads API keyword planning services.
3. Review search demand, monthly trend, competition, bid ranges, and close variants.
4. Mark keyword themes as prioritize, hold, reject, or needs more research.
5. Export a local campaign build sheet for manual review.
6. If advertising proceeds, create and manage the campaign manually in the Google Ads UI.

The tool does not create, edit, pause, remove, or otherwise mutate campaigns, ad groups, ads, keywords, budgets, bids, billing settings, users, or account structure.

Planned Google Ads API Use

The initial implementation is read-only and limited to keyword planning and minimal account-selection reads.

Allowlisted services:

• KeywordPlanIdeaService.GenerateKeywordIdeas
  • expands Search campaign seed concepts into keyword ideas;
  • uses language, geo target, and network settings selected by the internal user.
• KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • retrieves historical metrics for reviewed candidate keywords;
  • returns average monthly searches, monthly search volume trend, competition, competition index, bid estimates, average CPC when available, and close variants.
• CustomerService.ListAccessibleCustomers
  • identifies accessible Google Ads accounts for account selection.
• GoogleAdsService.Search or GoogleAdsService.SearchStream
  • used only for narrow account-selection reads when required, such as customer ID, descriptive name, currency, and time zone.

Estimated normal use is 5-20 planning runs per day, usually two KeywordPlanIdeaService calls per run. The private implementation is expected to use request deduplication, local caching, exponential backoff, and local operation caps.

Explicitly Out of Scope

The initial implementation will not use:

• campaign, ad group, ad, keyword, bid, or budget mutate operations;
• billing, payment, invoice, or account-budget operations;
• user access or invitation management;
• Customer Match, remarketing, conversion upload, or user data upload functionality;
• RecommendationService.ApplyRecommendation or RecommendationService.DismissRecommendation;
• BatchJobService;
• third-party account management;
• public API access or resale access;
• Google Search result scraping.

Output

The planned output is a local campaign build sheet for internal review.

Example fields:

• campaign_type
• campaign_theme
• ad_group_theme
• source_seed
• keyword_text
• close_variants
• match_type_hypothesis
• negative_keyword_candidate
• geo_target_constant
• language_constant
• avg_monthly_searches
• monthly_search_volumes
• competition
• competition_index
• low_top_of_page_bid_micros
• high_top_of_page_bid_micros
• avg_cpc_micros
• budget_hypothesis
• landing_page_readiness
• manual_google_ads_ui_action
• review_status
• notes

Outputs are local planning artifacts. They are not published, sold, sublicensed, or redistributed.

Privacy and Credential Handling

This public repository does not contain API keys, OAuth client secrets, refresh tokens, developer tokens, raw exports, customer data, or private planning outputs.

The private implementation is expected to use a single-user OAuth desktop flow for the applicant's own Google Ads account. Refresh tokens and other credentials are stored outside the repository, preferably in macOS Keychain or an encrypted local credential store. Local credential files, if any are used, should be restricted to the local user account.

The repository excludes generated outputs, token caches, local databases, credential files, and raw API responses through .gitignore.

Current Status

This public repository is a lightweight public overview and minimal CLI scaffold for the private internal planning tool. It documents the intended Google Ads API scope and safety boundaries. The working implementation is expected to proceed after the appropriate Google Ads API access level is approved.

python main.py --help
python main.py --json

Access Model

• Owner/operator: Individual / Nine-Shell.
• Users: internal user only.
• Account scope: Google Ads accounts owned or controlled by the applicant.
• Initial campaign type: Search.
• Initial targeting context: Japan and Japanese-language campaign planning.
• External clients: none.
• Public users: none.
• Campaign mutation: none.

License

MIT License.