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"

Supported Languages

• Python
• PHP
• Ruby
• Java
• C#

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.

By default, Python is used for code generation. You can change this by prefacing your prompt with 'in ' where is one of the supported languages. For example, 'in java' or 'in php'. This will then become the default language for 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. setup.sh (Linux/macOS) or setup.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 setup script

   • Linux/macOS:
     • Ensure that jq is installed.
     • Run ./setup.sh.
       • By default (no arguments), this installs ALL supported client libraries to $HOME/gaada.
       • To install specific languages, use flags: ./setup.sh --python --php.
       • Execute ./setup.sh --help for more details.
   • Windows:
     • Open PowerShell and run .\setup.ps1.
       • By default, this installs ALL supported client libraries to $HOME\gaada.
       • To install specific languages, use parameters: .\setup.ps1 -Python -Php.

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 setup.sh / setup.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",
      "/path/to/your/google-ads-php"
    ]
  }
}
```
*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"

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.
• 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.

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.

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.