Unlock SEO Insights: Automate Keyword Research with Python & Google Ads API

import os
import pandas as pd
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

# --- Configuration ---
# Ensure your `google-ads.yaml` file is in your home directory.
# This script will automatically use it for authentication.
# For language and location targeting:
# Geo Target Constant IDs: https://developers.google.com/google-ads/api/reference/data/geotargets
# Language Constant IDs: https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
LOCATION_IDS = ["2840"]  # USA
LANGUAGE_ID = "1000"    # English

def get_keyword_metrics(client, customer_id, keywords):
    """
    Fetches search volume and other metrics for a list of keywords.
    """
    keyword_plan_idea_service = client.get_service("KeywordPlanIdeaService")
    
    # Create the request object with our targeting and keywords
    request = client.get_type("GenerateKeywordIdeasRequest")
    request.customer_id = customer_id
    request.language = client.get_service("GoogleAdsService").language_constant_path(LANGUAGE_ID)
    request.geo_target_constants = [
        client.get_service("GoogleAdsService").geo_target_constant_path(location_id)
        for location_id in LOCATION_IDS
    ]
    request.keyword_seed.keywords.extend(keywords)
    request.historical_metrics_options.include_average_cpc = True # Include CPC data

    try:
        print("Fetching keyword metrics from Google Ads API...")
        response = keyword_plan_idea_service.generate_keyword_ideas(request=request)
        
        results = []
        for idea in response.results:
            metrics = idea.keyword_idea_metrics
            competition = metrics.competition.name if metrics.competition else "UNKNOWN"
            results.append({
                "Keyword": idea.text,
                "Avg. Monthly Searches": metrics.avg_monthly_searches,
                "Competition": competition,
                "Low CPC ($)": metrics.low_top_of_page_bid_micros / 1_000_000 if metrics.low_top_of_page_bid_micros else 0,
                "High CPC ($)": metrics.high_top_of_page_bid_micros / 1_000_000 if metrics.high_top_of_page_bid_micros else 0,
            })
        return results
        
    except GoogleAdsException as ex:
        print(f'Request with ID "{ex.request_id}" failed with status "{ex.error.code().name}" and includes the following errors:')
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        return None

def main():
    print("\n--- SEO Keyword Research Automation Tool ---")
    
    # --- 1. Initialize Google Ads Client ---
    try:
        # The client will look for the `google-ads.yaml` in your home directory.
        googleads_client = GoogleAdsClient.load_from_storage()
    except Exception as e:
        print(f"Failed to initialize Google Ads client. Ensure 'google-ads.yaml' is configured correctly. Error: {e}")
        return

    # --- 2. Get Customer ID ---
    # This should be the ID of the Google Ads account you have API access to.
    # It should NOT have hyphens.
    customer_id = input("Enter your Google Ads Customer ID (e.g., 1234567890): ").strip().replace("-", "")
    
    # --- 3. Load Keywords from File ---
    keyword_file = "keywords.txt"
    if not os.path.exists(keyword_file):
        print(f"\nError: '{keyword_file}' not found. Please create it and add your keywords, one per line.")
        return
        
    with open(keyword_file, 'r') as f:
        keywords = [line.strip() for line in f if line.strip()]
        
    if not keywords:
        print("Error: No keywords found in 'keywords.txt'.")
        return
        
    print(f"\nFound {len(keywords)} keywords to analyze.")

    # --- 4. Fetch Metrics and Generate Report ---
    keyword_data = get_keyword_metrics(googleads_client, customer_id, keywords)

    if keyword_data:
        # Use pandas to create a clean DataFrame and export to CSV
        df = pd.DataFrame(keyword_data)
        output_file = "keyword_report.csv"
        df.to_csv(output_file, index=False)
        print(f"\n\033[92mSuccess!\033[0m Report generated: {output_file}")
    else:
        print("\n\033[91mFailed to generate report.\033[0m Please check the error messages above.")

if __name__ == "__main__":
    main()