0
# Google Ads Integration
1
2
Google Ads API integration with OAuth authentication, account management, and reporting capabilities. Supports campaign data extraction and automated reporting workflows for digital advertising management.
3
4
## Capabilities
5
6
### Google Ads API Hook
7
8
Core hook for connecting to Google Ads API with support for OAuth Service Account Flow and Application Default Credentials authentication.
9
10
```python { .api }
11
class GoogleAdsHook(GoogleBaseHook):
12
def __init__(
13
self,
14
gcp_conn_id: str = "google_cloud_default",
15
google_ads_conn_id: str = "google_ads_default",
16
api_version: str = "v16",
17
**kwargs
18
): ...
19
20
def get_service(self, service_name: str, version: Optional[str] = None): ...
21
def search(
22
self,
23
client_ids: List[str],
24
query: str,
25
page_size: int = 1000,
26
**kwargs
27
): ...
28
def search_stream(
29
self,
30
client_ids: List[str],
31
query: str,
32
**kwargs
33
): ...
34
def list_accessible_customers(self): ...
35
def get_customer(self, client_id: str): ...
36
```
37
38
### Account Management
39
40
Operations for listing and managing Google Ads accounts.
41
42
```python { .api }
43
class GoogleAdsListAccountsOperator(BaseOperator):
44
"""
45
Lists all Google Ads accounts accessible by the authenticated user.
46
47
Args:
48
gcp_conn_id (str): The connection ID for Google Cloud Platform
49
google_ads_conn_id (str): The connection ID for Google Ads API
50
api_version (str): Google Ads API version to use
51
52
Returns:
53
List of accessible customer accounts with metadata
54
"""
55
def __init__(
56
self,
57
gcp_conn_id: str = "google_cloud_default",
58
google_ads_conn_id: str = "google_ads_default",
59
api_version: str = "v16",
60
**kwargs
61
): ...
62
```
63
64
### Data Export
65
66
Transfer Google Ads data to Google Cloud Storage for further processing and analysis.
67
68
```python { .api }
69
class GoogleAdsToGcsOperator(BaseOperator):
70
"""
71
Exports Google Ads data to Google Cloud Storage using GAQL queries.
72
73
Args:
74
client_ids (List[str]): Google Ads customer IDs to query
75
query (str): Google Ads Query Language (GAQL) query
76
obj (str): GCS object path for output
77
bucket (str): GCS bucket name
78
gcp_conn_id (str): The connection ID for Google Cloud Platform
79
google_ads_conn_id (str): The connection ID for Google Ads API
80
api_version (str): Google Ads API version to use
81
gzip (bool): Whether to gzip the output file
82
83
Returns:
84
GCS object path of exported data
85
"""
86
def __init__(
87
self,
88
client_ids: List[str],
89
query: str,
90
obj: str,
91
bucket: str,
92
gcp_conn_id: str = "google_cloud_default",
93
google_ads_conn_id: str = "google_ads_default",
94
api_version: str = "v16",
95
gzip: bool = False,
96
**kwargs
97
): ...
98
```
99
100
## Authentication Setup
101
102
Google Ads integration requires OAuth authentication setup:
103
104
```python
105
# Connection configuration for Google Ads API
106
connection_config = {
107
"conn_id": "google_ads_default",
108
"conn_type": "google_ads",
109
"login": "customer_id", # Your Google Ads customer ID
110
"password": "", # Leave empty
111
"extra": {
112
"developer_token": "your_developer_token",
113
"client_id": "your_oauth_client_id",
114
"client_secret": "your_oauth_client_secret",
115
"refresh_token": "your_refresh_token",
116
"login_customer_id": "manager_account_id" # Optional: for manager accounts
117
}
118
}
119
```
120
121
## Usage Examples
122
123
### Basic Account Listing
124
125
```python
126
from airflow import DAG
127
from airflow.providers.google.ads.operators.ads import GoogleAdsListAccountsOperator
128
from datetime import datetime
129
130
dag = DAG(
131
'google_ads_accounts',
132
default_args={'start_date': datetime(2023, 1, 1)},
133
schedule_interval='@daily',
134
catchup=False
135
)
136
137
list_accounts = GoogleAdsListAccountsOperator(
138
task_id='list_accounts',
139
google_ads_conn_id='google_ads_default',
140
dag=dag
141
)
142
```
143
144
### Campaign Data Export
145
146
```python
147
from airflow import DAG
148
from airflow.providers.google.ads.transfers.ads_to_gcs import GoogleAdsToGcsOperator
149
from datetime import datetime
150
151
dag = DAG(
152
'google_ads_export',
153
default_args={'start_date': datetime(2023, 1, 1)},
154
schedule_interval='@daily',
155
catchup=False
156
)
157
158
export_campaigns = GoogleAdsToGcsOperator(
159
task_id='export_campaigns',
160
client_ids=['1234567890'],
161
query='''
162
SELECT
163
campaign.id,
164
campaign.name,
165
campaign.status,
166
metrics.impressions,
167
metrics.clicks,
168
metrics.cost_micros
169
FROM campaign
170
WHERE segments.date DURING LAST_7_DAYS
171
''',
172
bucket='my-ads-data-bucket',
173
obj='campaigns/{{ ds }}/campaign_data.jsonl',
174
google_ads_conn_id='google_ads_default',
175
gcp_conn_id='google_cloud_default',
176
dag=dag
177
)
178
```
179
180
### Advanced Reporting Pipeline
181
182
```python
183
from airflow import DAG
184
from airflow.providers.google.ads.transfers.ads_to_gcs import GoogleAdsToGcsOperator
185
from airflow.providers.google.cloud.transfers.gcs_to_bigquery import GCSToBigQueryOperator
186
from datetime import datetime
187
188
dag = DAG(
189
'google_ads_to_bigquery',
190
default_args={'start_date': datetime(2023, 1, 1)},
191
schedule_interval='@daily',
192
catchup=False
193
)
194
195
# Export Google Ads data to GCS
196
export_ads_data = GoogleAdsToGcsOperator(
197
task_id='export_ads_data',
198
client_ids=['1234567890', '0987654321'],
199
query='''
200
SELECT
201
customer.id,
202
campaign.id,
203
campaign.name,
204
ad_group.id,
205
ad_group.name,
206
segments.date,
207
metrics.impressions,
208
metrics.clicks,
209
metrics.conversions,
210
metrics.cost_micros
211
FROM keyword_view
212
WHERE segments.date = '{{ ds }}'
213
''',
214
bucket='ads-data-lake',
215
obj='raw/ads_performance/{{ ds }}/performance.jsonl',
216
google_ads_conn_id='google_ads_default',
217
dag=dag
218
)
219
220
# Load data into BigQuery
221
load_to_bigquery = GCSToBigQueryOperator(
222
task_id='load_to_bigquery',
223
bucket='ads-data-lake',
224
source_objects=['raw/ads_performance/{{ ds }}/performance.jsonl'],
225
destination_project_dataset_table='analytics.ads_performance.daily_performance',
226
schema_fields=[
227
{'name': 'customer_id', 'type': 'STRING', 'mode': 'REQUIRED'},
228
{'name': 'campaign_id', 'type': 'STRING', 'mode': 'REQUIRED'},
229
{'name': 'campaign_name', 'type': 'STRING', 'mode': 'NULLABLE'},
230
{'name': 'ad_group_id', 'type': 'STRING', 'mode': 'REQUIRED'},
231
{'name': 'ad_group_name', 'type': 'STRING', 'mode': 'NULLABLE'},
232
{'name': 'date', 'type': 'DATE', 'mode': 'REQUIRED'},
233
{'name': 'impressions', 'type': 'INTEGER', 'mode': 'NULLABLE'},
234
{'name': 'clicks', 'type': 'INTEGER', 'mode': 'NULLABLE'},
235
{'name': 'conversions', 'type': 'FLOAT', 'mode': 'NULLABLE'},
236
{'name': 'cost_micros', 'type': 'INTEGER', 'mode': 'NULLABLE'},
237
],
238
source_format='NEWLINE_DELIMITED_JSON',
239
write_disposition='WRITE_TRUNCATE',
240
dag=dag
241
)
242
243
export_ads_data >> load_to_bigquery
244
```
245
246
## Types
247
248
```python { .api }
249
from typing import List, Optional, Dict, Any, Union
250
from airflow.models import BaseOperator
251
252
# Google Ads specific types
253
CustomerInfo = Dict[str, Any]
254
CampaignInfo = Dict[str, Any]
255
AdGroupInfo = Dict[str, Any]
256
GoogleAdsQuery = str
257
ClientId = str
258
GoogleAdsApiVersion = str
259
260
# Authentication types
261
DeveloperToken = str
262
RefreshToken = str
263
OAuthCredentials = Dict[str, str]
264
```