Google Ads API Developer Assistant

The Google Ads API Developer Assistant is a powerful extension for the Gemini CLI designed to accelerate your Google Ads API workflows. The Assistant lets you interact with the Google Ads API using natural language, making it easier to ask questions, generate code, retrieve data, and troubleshoot issues directly within your terminal.

Benefits

  • Boost productivity: Spend less time searching documentation and writing boilerplate code.
  • Simplify complex tasks: Generate Google Ads Query Language (GAQL) and client library code from simple English prompts.
  • Learn the API: Understand API concepts and see how natural language requests translate to executable code.
  • Interactive debugging: Get help understanding errors and step-by-step guidance on troubleshooting.
  • Streamlined workflow: Keep your development and testing loop within the command line.

Prerequisites

Before you begin, make sure you have the following:

  1. Google Ads API Access:

  2. Software:

    • Python 3.10 or newer. Python is the default language, so you must have this installed and on your path.
    • The Gemini CLI installed.
    • jq (command-line JSON processor). The setup script will attempt to install this if missing.

  3. Repository:

    • A local clone of the google-ads-api-developer-assistant repository from GitHub: none git clone https://github.com/googleads/google-ads-api-developer-assistant.git

Get started

  1. Navigate to the project directory: none cd <full path>/google-ads-api-developer-assistant

  2. Run the setup script: This script configures the Gemini CLI to use the assistant's GEMINI.md context files and necessary tools. none ./setup.sh If you are on Windows, run the setup.ps1 PowerShell script.

  3. Start the Gemini CLI: none gemini

  4. Interact with the Assistant: You can now ask questions or give commands in natural language.

Key features

  • Natural language Q&A: Ask questions about Google Ads API features, best practices, or specific resources.

    • "What are the available campaign types?"
    • "How do I filter by date in GAQL?"
    • "Explain the difference between click_view and impression_view."

  • Code generation: Generate GAQL queries and executable Python code snippets.

    • "Show me campaigns with the most conversions in the last 30 days."
    • "Get all enabled ad group names for campaign ID 12345."
    • "Find disapproved ads across all campaigns." Generated code is saved in the saved_code/ directory.

  • Direct API execution: Run generated read-only Python scripts directly from the Gemini CLI and view formatted results in your terminal. After the Assistant has generated the code, you will receive an on-screen prompt:

To run this script, you will need to replace YOUR_CUSTOMER_ID with your actual Google Ads
customer ID and execute the following command in your shell: <command>

Enter run, and the script will execute in the Assistant context.

  • CSV export: Save tabular results from API calls to a CSV file.

    • "Save the results to a CSV file." Files are saved in the saved_csv/ directory.

  • Troubleshooting assistance: Get help with error messages or unexpected API behavior.

    • "I got the error 'AuthenticationError.OAUTH_TOKEN_INVALID', what should I do?"
    • "Why am I not seeing any results for my query?"

Example use cases

  • Reporting:
    • "Get me the top 5 keywords by cost for last month for customer 12345678."
  • Account structure:
    • "List all campaign names and their IDs."
  • Troubleshooting:
    • "I uploaded 100 conversions, but only 78 appear in the UI. How can I debug this using the API?"
  • Learning:
    • "Walk me through how to create a Performance Max campaign using the API."

Community and support

Contribution guidelines

Contributions are welcome! See the CONTRIBUTING.md file in the GitHub repository for guidelines.