Package: adsctl
Google Ads API CLI and PromptGoogle 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.
Likepsqlfor the Google Ads API.A command line tool for managing Google Ads resources.
Likekubectlfor the Google Ads API.Centralized configuration with multiple account managementAutomatically update refresh tokenPython API with Pandas integrationInstallationpipinstalladsctlGetting startedRequirements:All the requirements to use the Google Ads API including a Developer Token and OAuth2 credentialsSeeGoogle Ads API Quickstartfor more details.ConfigurationThis project manages it's own configuration files.
To create the configuration file run:adsctlconfig# Open the location of the config filesadsctlconfigexploreOpen 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:adsctlauth<path-to-secret.json>The token is saved automatically in the config file.
You can see it by running:# View configadsctlconfigviewMultiple AccountsYou 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:$adsctlconfigset-accountanother
$adsctlconfigget-account
anotherGAQL PromptAn interactive shell for executing GAQL queries against the Google Ads API.$gaql

>>>SELECTcampaign.id,campaign.nameFROMcampaignORDERBYcampaign.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 intableformat but you can control the output
format with the-ooption:# Print the plain protobuf response$gaql-oplain# Print the contents of a CSV file$gaql-ocsvYou 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'-ocsv>my-query.csvThis 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'-ocsv-files

$ls
campaign.csvQuery variablesYou can specify one or more variables using the jinja syntax, those
variables will be replaced with the values specified in the-voptions.gaql-c'SELECT campaign.id, campaign.name FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id'-vid=123456789You can also pass-vwithout a command and use this the variables in the prompt
queries:$gaql-vid=123456789-vfield=name

>>>SELECTcampaign.id,campaign.{{field}}FROMcampaignWHEREcampaign.id={{id}}ORDERBYcampaign.idOther optionsYou can overwrite the account and customer ID using the-aand-ioptions.
Seegaql --helpfor more details.CLICampaign ManagementGet campaigns```shell
adsctlgetcampaignName                                          Status             Id
--------------------------------------------  --------  -----------
Interplanetary Cruise Campaign #168961427368  Paused    20370195066
Interplanetary Cruise Campaign #168961215970  Paused    20379497161Status Managementadsctleditcampaign-i<campaign-id>statusenabled

adsctleditcampaign-i20370195066statusenabledadsctlgetcampaignName                                          Status             Id
--------------------------------------------  --------  -----------
Interplanetary Cruise Campaign #168961427368  Enabled   20370195066
Interplanetary Cruise Campaign #168961215970  Paused    20379497161Update budgetadsctleditcampaign-i<campaign-id>budget<amount>Python APIYou can also use the Python API to easily execute GAQL queries
and get the results as a Python dict or pandas DataFrame.importadsctlasads# Read config file and creates the Google Ads clientgoogle_ads=ads.GoogleAds()# Execute GAQL queryget_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_typeFROM campaignWHERE segments.date DURING LAST_7_DAYSAND campaign.status != '{{ status }}'"""tables=google_ads.query(get_campaigns_query,params={"status":"REMOVED"}})# Print Pandas DataFramesfortable_name,tableintables.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      1000000DisclaimerThis 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.