GoogleAdsQueryTool

Number of Downloads per month

This is a package you can use to query reporting data from the Google Ads API.

Build status

Requirements

• Python 3.9+

Installation

pip install googleadsquerytool

Features

• Distributed via PyPI.
• Wrapper around the Google Ads API for easy reporting.
• Returns data in the form of a pandas DataFrame.

Example usage

Before installing the library, you will need a developer token and client customer ID. Instructions on how to obtain them are outlined here. After you have successfully obtained your developer token and have successfully authenticated as per these instructions you need to create a .yaml file (example) and place it in the home directory of your computer or virtual private server.

from googleadsquerytool import create_dict, GoogleAdsDataRetriever

# These represent your SELECT fields for a GAQL query:
fields = ['campaign.name', 'metrics.impressions', 'metrics.cost_micros', 'metrics.clicks']

# This represents the FROM portion of your GAQL query:
resource_name = 'campaign'

# Additional where clauses can be passed but are not mandatory
custom_where_clause = 'campaign.status = "ENABLED" AND campaign.serving_status = "SERVING"'

# Dictionary to append rows into:
ads_data = create_dict(fields)

# Create client object:
client = GoogleAdsDataRetriever(customer_id='Customer_id_that_your_mcc_account_has_access_to')

# Optional: If your Google Ads configuration file is in a custom location or has a custom name:
# client = GoogleAdsDataRetriever(customer_id='Customer_id_that_your_mcc_account_has_access_to', config_path='/path/to/your_config.yaml')

# Make a request to the API:
google_ads_data_df = client.get_data(
   query_fields=ads_data, 
   from_resource_name=resource_name, 
   headers=False, # Pass a list of headers that you would like to have
   start_date='2024-01-01',
   end_date='2024-01-31', 
   where=custom_where_clause, 
   remove_zero_impressions=True)

For some queries, such as those involving campaign labels, start and end dates cannot be specified, nor can zero-impression rows be removed. In these cases, you can leave these fields blank.

Configuration File

By default, the library looks for a Google Ads configuration file named google-ads.yaml in your home directory. If your configuration file is in a different location or has a different name, you can specify the path using the config_path parameter:

# Using a custom configuration file path
client = GoogleAdsDataRetriever(
    customer_id='Customer_id_that_your_mcc_account_has_access_to',
    config_path='/path/to/your_custom_config.yaml'
)

fields = ['campaign.name', 'label.name', 'label.status', 'label.text_label.background_color']

resource_name = 'campaign_label'

label_data = create_dict(fields)

Header_names = ['Campaign', 'Label', 'Label Status', 'Label Color']

label_df = client.get_data(
   query_fields=label_data,
   from_resource_name=resource_name,
   headers=Header_names,
   remove_zero_impressions=False)