Google Ads API Developer Assistant (Gemini CLI Extension)

TL;DR: This extension for the Gemini CLI lets you interact with the Google Ads API using natural language. Ask questions, generate GAQL and code in several languages, and execute API calls that read directly in your terminal.

Overview

The Google Ads API Developer Assistant enhances the Gemini CLI to streamline workflows for developers working with the Google Ads API. Use natural language prompts to:

• Get answers to Google Ads API questions.
• Construct Google Ads Query Language (GAQL) queries.
• Generate executable code in several languages using our client libraries for context.
• Retrieve and display data from the API.

This extension leverages gemini-cli's ability to use GEMINI.md files and the settings in .gemini/settings.json to provide persistent context, making interactions more efficient and accurate.

Key Features

• Natural Language Q&A: Ask about Google Ads API concepts, fields, and usage in plain English.

  • "What are the available campaign types?"
  • "Tell me about reporting for Performance Max campaigns."
  • "How do I filter by date in GAQL?"

• Natural Language to GAQL & Client Library Code: Convert requests into executable code using the Google Ads Client Libraries.

  • Code is saved to saved/code/.
  • "Show me campaigns with the most conversions last 30 days."
  • "Get all ad groups for customer '123-456-7890'."
  • "Find disapproved ads across all campaigns."

• Direct API Execution: Run the generated Python code from the CLI and view results, often formatted as tables.

• CSV Export: Save tabular API results to a CSV file in the saved/csv/ directory.

  • "Save results to a csv file"

• Conversion Troubleshooting & Diagnostics: Generate structured diagnostic reports to debug offline conversion issues.

  • Reports are saved to saved/data/.
  • "Troubleshoot my conversions for customer '123-456-7890'."

• Validate Complex GAQL Queries: Validate complex GAQL queries to ensure they are valid and will return the expected results. (This query is invalid. Validate it in the Assistant and see what happens/serv)

  • "validate: SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, ad_group.id, ad_group.name, ad_group.status, ad_group_ad.ad.id, ad_group_ad.status, ad_group_ad.ad.type, ad_group_ad.policy_summary.policy_topic_entries, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions, metrics.conversions_value, segments.date, segments.device, segments.ad_network_type, segments.slot, segments.day_of_week FROM ad_group_ad WHERE campaign.status = 'ENABLED' AND ad_group.status = 'ENABLED' AND ad_group_ad.status = 'ENABLED' AND segments.date DURING LAST_39_DAYS AND metrics.impressions > 100 ORDER BY metrics.clicks DESC LIMIT 500"

Supported Languages

• Python
• PHP
• Ruby
• Java
• C# (.NET)

Code generated by Python, PHP, and Ruby can be executed directly from the CLI. Code generated by Java and C# must be compiled and executed separately. This is because of security policies enforced by the Gemini CLI. For C# code generation, use 'in dotnet' to set the context.

By default, Python is used for code generation. You can change this by prefacing your prompt with 'my preferred language is ' where is one of the supported languages. For example, 'my preferred language is java' or 'my preferred language is php'. This will then become the default language for user code generation for the duration of your session.

Prerequisites

1. Familiarity with Google Ads API concepts and authentication.
2. A Google Ads API developer token.
3. A configured credentials file in your home directory if using Python, PHP, or Ruby.
4. Gemini CLI installed (see Gemini CLI docs).
5. A local clone of each client library for the languages you want to use. install.sh (Linux/macOS) or install.ps1 (Windows) can set this up for you.
6. Python >= 3.10 installed and available on your system PATH. This is required for executing the default generated Python code directly from the CLI.

Setup

1. Install Gemini CLI: Ensure that Gemini CLI is installed. Pro tip: Before starting the installation read the authentication section.

2. Clone the Extension: git clone https://github.com/googleads/google-ads-api-developer-assistant. This becomes your project directory. You need to be in this directory when you run gemini-cli.

3. Run install script

   • Linux/macOS:
     • Ensure that jq is installed.
     • Run ./install.sh.
       • By default (no arguments), this installs the Python client library to the client_libs/ directory within this project.
       • To install additional languages, use flags: ./install.sh --php --ruby --dotnet.
       • Execute ./install.sh --help for more details.
   • Windows:
     • Open PowerShell and run .\install.ps1.
       • By default, this installs the Python client library to the client_libs\ directory within this project.
       • To install additional languages, use parameters: .\install.ps1 -Php -Ruby -Dotnet.

4. Configure Credentials: Make sure your API credentials configuration files are in your $HOME directory. Each language has its own configuration file naming convention and structure.

5. Optional: Default Customer ID: To set a default customer ID, create a file named customer_id.txt in the google-ads-api-developer-assistant directory with the content customer_id:YOUR_CUSTOMER_ID (e.g., customer_id: 1234567890). You can then use prompts like "Get my campaigns" and the Assistant will use the CID for the request.

Manual Setup

This is an alternative method to running install.sh / install.ps1. Replace Step 3 above with the following:

a. Clone Google Ads Client Libraries: Clone the client libraries repository to a local directory that is NOT under the Google Ads API Developer Assistant project directory. This provides context for code generation.

b. Set Context in Gemini: The gemini command must be run from the root of the google-ads-api-developer-assistant project directory. Configure the context paths in .gemini/settings.json: * Edit /path/to/your/google-ads-api-developer-assistant/.gemini/settings.json. * Add the full absolute paths to the context.includeDirectories array: * Your google-ads-python library clone. * The api_examples directory within this project. * The saved/code directory within this project.

**Example `.gemini/settings.json`:**
```json
{
  "context": {
    "includeDirectories": [
      "/path/to/your/google-ads-api-developer-assistant/api_examples",
      "/path/to/your/google-ads-api-developer-assistant/saved/code",
      "/path/to/your/google-ads-python",
      "client_libs/google-ads-php",
      "client_libs/google-ads-ruby"
    ]
  }
}
```
*Note: Including `client_libs/google-ads-php` or `client_libs/google-ads-ruby` will automatically configure those languages by copying `~/google_ads_php.ini` or `~/google_ads_config.rb` to the `config/` directory at session start. Python is always configured.*
*Note: Replace the placeholder paths with the actual absolute paths on your system.*

Usage

1. Start Gemini CLI:

   cd /path/to/google-ads-api-developer-assistant
   gemini

2. Ask a question:

   "What are the resource names for my enabled campaigns sorted by campaign id"

3. Generate Code:

   "Get me the top 5 campaigns by cost last month for customer 1234567890"

4. Execute and Save:

   "Run the code" ... (results displayed) ... "Save the results to csv"

Customm Commands

There is a bug in /help. It does not list custom commands defined in .gemini/commands under the project directory.

This is a partial list of custom commands:

• /explain <request> - Format the response from the model to be more readable. It attempts to use real world analogies to explain a concept.
• /step_by_step <request> - Format the response as series of steps. Show the model's thinking process. This is useful for debugging.
• /conversions_support_data - Collects structured diagnostic data for gTech conversion troubleshooting and saves a report to saved/data/.

To see the full list, from within the Assistant, ls -l .gemini/commands. This will provide a list of the .toml files that define the commands. For example, explain.toml can be executed as /explain <your request>.

Or, you can execute run list_commands.py from within the Assistant to see the full list with descriptions.

Directory Structure

• google-ads-api-developer-assistant/: Root directory. Launch gemini from here.
• .gemini/: Contains settings.json for context configuration.
• api_examples/: Contains example API request/response files.
• saved/code/: Stores Python code generated by Gemini.
• saved/csv/: Stores CSV files exported from API results.
• saved/data/: Stores diagnostic and troubleshooting reports.
• customer_id.txt: (Optional) Stores the default customer ID.

Mutate Operations

The Assistant is designed to generate code for mutate operations (e.g., creating campaigns, adding users) but will not execute them. This execution policy ensures you have full control over any changes to your Google Ads account. You must review the generated code for accuracy and execute it manually outside of the Assistant.

Known Quirks

• The underlying model may have been trained on an older API version. It may occasionally generate code with deprecated fields. Execution errors often provide feedback that allows Gemini CLI to self-correct on the next attempt, using the context from the client libraries. To avoid these errors, we always search for the latest version of the API when initializing the session and ask you to verify the version.

• The exit hook may execute cleanup_config.py twice to remove the temporary configuration files. This is a known problem that does not affect performance.

Maintenance

We will periodically release updates to both this extension and the client libraries. To ensure you are using the latest versions, run update.sh (Linux/macOS) or update.ps1 (Windows) when a new version of the API is published or a new version of a client library is released.

Uninstallation

If you wish to remove the extension and the project directory, you can use the uninstallation scripts:

• Linux/macOS:

  ./uninstall.sh

• Windows:

  .\uninstall.ps1

Caution

These scripts will prompt for confirmation before deleting the entire project directory.

Contributing

Please see CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

Support

Use the GitHub Issues tab for bug reports, feature requests, and support questions.

License

Apache License 2.0. See the LICENSE file.