Install and use the Google Ads API Developer Assistant

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.
    • gemini-cli installed.
    • jq (command-line JSON processor). The installation script will attempt to install this if missing.

  3. Repository:

Get started

  1. Navigate to the project directory:

    cd <full path>/google-ads-api-developer-assistant

  2. Run the setup script: This script configures gemini-cli to use the assistant's GEMINI.md context files and necessary tools.

    ./install.sh

    If you are on Windows, run the setup.ps1 PowerShell script.

  3. Start gemini-cli:

    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 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 if your default language is Python, Ruby, or PHP. Compiled languages will not run because of security policies.

  • 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:
    • "/explain what a shared set is"
  • Code Generation:
    • "Write code to create a Performance Max campaign for company name."

Community and support

Contribution guidelines

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