Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/googleads/google-ads-api-developer-assistant


https://github.com/googleads/google-ads-api-developer-assistant

Last synced: 5 months ago
JSON representation

Awesome Lists containing this project

README 

          
# 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](https://github.com/google-gemini/gemini-cli)).

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](https://github.com/google-gemini/gemini-cli) is installed. **Pro tip**: Before starting the installation read the [authentication](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#-authentication-options) 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](https://github.com/jqlang/jq?tab=readme-ov-file#installation) 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:**

    ```bash

    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` - Format the response from the model to be more readable.

* `/step_by_step` - Format the response as series of steps. Show the model's thinking process. This is useful for debugging.



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



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.

*   `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.