Install and use the Google Ads API Developer Assistant

Prerequisites

Before you begin, make sure you have the following:

1. Google Ads API Access:

   • A Google Ads API developer token .
   • A Google Ads Configuration File configured with your developer token, OAuth 2.0 credentials, and customer ID, typically located in your home directory. See the client library configuration guide .
   • Familiarity with Google Ads API concepts and authentication.

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:

   • A local clone of the google-ads-api-developer-assistant repository from GitHub:

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

• GitHub issues:Report bugs, suggest features, or ask for help on the Issues tab in the repository.
• Discord:Join the discussion in the #ads-api-ai-tools channel on the Google Advertising and Measurement Community Discord server .
• Feedback:Share your feedback through this survey form .

Contribution guidelines

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