Google Ads Interface for humans.
This is a work in progress, please open an issue if you find any bugs or have any suggestions.
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 multiple account management
- Automatically update refresh token
- Python API with Pandas integration
pip install adsctl
Requirements:
- All the requirements to use the Google Ads API including a 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 new default config file and fill it with your credentials: Dev Token, Client ID, Client Secret and Customer ID.
To login and get a refresh token:
adsctl auth <path-to-secret.json>
The token is saved automatically in the config file. You can see it by running:
# View config
adsctl config view
You can manage multiple accounts in the config file by adding TOML sections.
current_account = "default"
[... default account ...]
[accounts.another]
developer_token = ""
customer_id = ""
login_customer_id = ""
[accounts.another.oauth]
client_id = ""
client_secret = ""
Set the current account:
$ adsctl config set-account another
$ adsctl config get-account
another
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 it uses the it in table
format but you can control the output
format with the -o
option:
# Print the plain protobuf response
$ gaql -o plain
# Print the contents of a CSV file
$ gaql -o csv
You can also run a single inline command and redirect the output to a file:
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
You can specify one or more variables using the jinja syntax, those
variables will be replaced with the values specified in the -v
options.
gaql -c 'SELECT campaign.id, campaign.name FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id' -v id=123456789
You can also pass -v
without a command and use this the variables in the prompt
queries:
$ gaql -v id=123456789 -v field=name
>>> SELECT campaign.id, campaign.{{ field }} FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id
You can overwrite the account and customer ID using the -a
and -i
options.
See gaql --help
for more details.
```shell
adsctl get campaign
Name Status Id
-------------------------------------------- -------- -----------
Interplanetary Cruise Campaign #168961427368 Paused 20370195066
Interplanetary Cruise Campaign #168961215970 Paused 20379497161
adsctl edit campaign -i <campaign-id> status enabled
adsctl edit campaign -i 20370195066 status enabled
adsctl get campaign
Name Status Id
-------------------------------------------- -------- -----------
Interplanetary Cruise Campaign #168961427368 Enabled 20370195066
Interplanetary Cruise Campaign #168961215970 Paused 20379497161
adsctl edit campaign -i <campaign-id> budget <amount>
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 creates the Google Ads 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 != '{{ status }}'
"""
tables = google_ads.query(get_campaigns_query, params={"status": "REMOVED"}})
# 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
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.