Google Ads API CLI and Prompt

Features:

• A command line tool for executing GAQL queries against the Google Ads API. Like psql for the Google Ads API.
• A command line tool for managing Google Ads resources. Like kubectl for the Google Ads API.
• Centralized configuration with (soon) multiple config file management
• Automatically update refresh token
• Simple Python API with Pandas integration

Google Ads Interface for humans.

Installation

pip install adsctl

Getting started

Requirements:

• All the requirements to use the Google Ads API including Ads Developer Token and OAuth2 credentials
• See Google Ads API Quickstart for more details.

This project manages it's own configuration files. To create the configuration file run:

adsctl config

# Open the location of the config files
adsctl config explore

Open the generated config file and fill it with your credentials: Dev Token, Client ID, Client Secret and Customer ID. Don't add the refresh_token.

To login and get a refresh token:

adsctl auth <path-to-secret.json>

The token is saved automatically in the configuration file.

GAQL Prompt

An interactive shell for executing GAQL queries against the Google Ads API.

$ gaql

>>> SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id
+----+-----------------------------+---------+-------------+
|    | resourceName                | name    |          id |
|----+-----------------------------+---------+-------------|
|  0 | customers/XXX/campaigns/YYY | name1   | 10000000000 |
|  1 | customers/XXX/campaigns/YYY | name2   | 10000000000 |
|  2 | customers/XXX/campaigns/YYY | name3   | 10000000000 |
+----+-----------------------------+---------+-------------+

By default adsctl prints it in "table" format but you can control the output format with the -o flag:

# Print the plain protobuf response
$ gaql -o plain

# Print a CSV response
$ gaql -o csv

You can also run a single commands and save the output to a file in the specified format:

$ gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv > my-query.csv

This assumes only table is returned but in more complex queries that include other resources or when using metrics or segments multiple tables are created. On those cases use the -o csv-files flag to save each table to a different file based on the table name.

$ gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv-files

$ ls
campaign.csv

CLI

Campaign Management

Status management

adsctl campaign -i <campaign-id> status enabled
adsctl campaign -i <campaign-id> status paused

Update budget

adsctl campaign -i <campaign-id> budget <amount>

Config

adsctl config show

Programmatic API

You can also use the Python API to easily execute GAQL queries and get the results as a Python dict or pandas DataFrame.

import adsctl as ads

# Read config file and create client
google_ads = ads.GoogleAds()

# Execute GAQL query
get_campaigns_query = """
SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'
"""

tables = adsctl.query(get_campaigns_query)

# Print Pandas DataFrames
for table_name, table in tables.items():
    print(table_name)
    print(table, "\n")

campaign
                                 resourceName   status  ...                      name optimizationScore
0  customers/XXXXXXXXXX/campaigns/YYYYYYYYYYY  ENABLED  ...               my-campaign          0.839904
[1 rows x 6 columns]

metrics
  clicks costMicros       ctr    averageCpc impressions
0    210    6730050  0.011457  32047.857143       18330

campaignBudget
                                       resourceName amountMicros
0  customers/XXXXXXXXXX/campaignBudgets/ZZZZZZZZZZZ      1000000

Or just directly make a search_stream request:

stream = app.search_stream(query)

for batch in stream:
    for row in batch.results:
        ...

Disclaimer

This is not an official Google product.

This repository is maintained by a Googler but is not a supported Google product. Code and issues here are answered by maintainers and other community members on GitHub on a best-effort basis.