Metadata-Version: 2.1
Name: googleadsquerytool
Version: 0.1.9
Summary: This is a package you can use to query reporting data from the Google Ads API.
Author: caspercrause
Author-email: ccrause07@gmail.com
Requires-Python: >=3.9,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: google-ads (>=29.0.0)
Requires-Dist: pandas (>1.4)
Description-Content-Type: text/markdown

# GoogleAdsQueryTool [![PyPI Version](https://img.shields.io/pypi/v/googleadsquerytool.svg)](https://pypi.org/project/googleadsquerytool/)


## Number of Downloads per month
![Downloads](https://img.shields.io/pypi/dm/googleadsquerytool)

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

## Build status
![Build Status](https://img.shields.io/badge/build-passing-brightgreen?label=build&color=lime)

## Requirements
[![Python Versions](https://img.shields.io/pypi/pyversions/googleadsquerytool)](https://pypi.org/project/googleadsquerytool/)

- **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](https://developers.google.com/google-ads/api/docs/get-started/introduction). After you have successfully obtained your developer token and have successfully [authenticated](https://developers.google.com/google-ads/api/docs/oauth/overview) as per these instructions you need to create a `.yaml` file ([example](https://github.com/googleads/google-ads-python/blob/main/google-ads.yaml)) 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:

```python
# 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)
 ```
