# Google Ads Import Integration V2

Google Ads is an online advertising platform that allows businesses to promote their products and services through digital ads across millions of Google partner websites and its services such as Google Search, YouTube, and Maps. This integration allows you to import Google Ads reports and metrics into Treasure Data to tailor-made your customer experiences, make data-driven decisions to optimize your campaigns, and achieve better marketing results

## Prerequisites

- Basic knowledge of Treasure Data™
- Basic understanding of [Google Ads performance data](https://support.google.com/google-ads/answer/2404036?hl=en&sjid=211862480303301723-AP)


## Requirements and Limitations

- The import job could fail if the data is too big. Using paging could fix that problem.
- Google might change the default views of its performance data from time to time, thus the below pre-defined metric collection of each report type might not be the same as the corresponding reports found on the Google Ads. However, missing metrics could be added to fulfill the data requirement.
- This article doesn't intend to list all available attributes, segments, metrics, and explanations for them. For more details, please refer to [Google Ads Query Builder](https://developers.google.com/google-ads/api/fields/v17/overview_query_builder), or the Report Editor feature which can be found on the Google Ads UI (Campaigns > Insights and reports > Report Editor)


## Import from Google Ads via TD Console

You must create and configure the data connection on TD Console before importing data. As part of the data connection, you provide the OAuth authentication of your Google Ads account to deploy the integration using the following steps.

![](/assets/screen-shot-2022-03-28-at-15.07.52.3cad2b46ae60f8077320ea9edfd3e1f3e6b38c3658d428682450fec957700f6d.7c52a81f.png)

1. Open TD Console
2. Navigate to **Integrations Hub > Catalog**
3. Search for and select **Google Ads V2**
4. Select **Create Authentication**and provide the OAuth of a Google account with access to the target Google Ads account
5. After being redirected back to the Integration Hub, repeat the above steps (this time your provided OAuth will be shown), enter a name for your authentication, and select **Done**.


### Create a Source

1. Open TD Console
2. Navigate to **Integrations Hub > Authentications**
3. Locate your new authentication and select **New Source**
4. On the first step `**1 - Connection**`, type a source name in the **Data Transfer Name** field, and select **Next**


### Identify a Source Table

Identify what data to be ingested into Treasure Data using the parameters below, and select **Next**.

This integration supports flexible ways to define your target data:

- Choose one of the 4 pre-defined report types, and pick up the desired Attributes, Segments, and Metrics. Or,
- Fill in a custom query valid for Google Ads to import necessary data. It is recommended to use this option together with the [Google Ads Query Builder](https://developers.google.com/google-ads/api/fields/v17/overview_query_builder)


![](/assets/adwordsv2b.c98f784aca54d18a6127fcb31283681502b8c09c677271b52e2939499adb4c4f.7c52a81f.png)

**Source Table Parameter**

| Parameter | Required | Type | Description |
|  --- | --- | --- | --- |
| Ads Account | Required | string | The ID of the target Google Ads account, with or without dashes |
| Ads Manager Account | Optional | string | The ID of the Google Manager account. This is required if the Ads Account is accessible via a manager account. |
| Enable Custom Query | Required | boolean | With this option enabled, a custom query can be used to declare the target data source. Refer to [Google Ads Query Builder](https://developers.google.com/google-ads/api/fields/v17/overview_query_builder) for more details. Otherwise, choose one of the pre-defined report types, and pick up the desired Attributes, Segments, and Metrics. |
| Report Type | Optional | string | Required if the Custom Query option is disabled. Each pre-defined report type will have its collections of Attributes, Segments, and Metrics. - Ad Performance (similar to the dashboard found on Campaigns > Campaigns > Ads) - Ad Group Performance (similar to the dashboard found on Campaigns > Campaigns > Ad groups) - Campaign Performance (similar to the dashboard found on Campaigns > Campaigns > Campaigns) - Keywords Performance (similar to the dashboard found on Campaigns > Audiences, keywords and content > Search keywords) |
| Include Negative Keywords | Optional | boolean | Enable negative keywords to ingest when the report type is Keywords Performance Report |
| Use predefined metrics | Optional | boolean | Use predefined metrics of the selected report type, instead of adding additional metrics |
| Attributes | Optional | array of string | List of additional attributes for the selected report type |
| Segments | Optional | array of string | At least 1 segment must be added for all the predefined report types. Only time segment is supported: Date, Day of week, Week, Month, Quarter, Year. When the Date Range is All Time, no time segment is required. Otherwise, one type of time segment is needed. |
| Metrics | Optional | array of string | List of additional metrics for the selected report type |
| Date Range | Optional | string | The date range of the target data. Supported values: - Custom Date: define your target range using Start Date and End Date - Today, Yesterday - Last 7 days, Last business week - This month, Last month - All time - Last 14 days, Last 30 days - This week from the previous Sunday to today - This week from the previous Monday to today - Last week from the previous Sunday to Saturday |
| Start Date | Optional | date | The start date of the custom date range in `yyyy-MM-dd` format |
| End Date | Optional | date | The end date of the custom date range in `yyyy-MM-dd` format |
| Incremental mode | Optional | boolean | Enable to run the job in incremental mode |


**Source Table Parameter - Custom Query**

| Parameter | Required | Type | Description |
|  --- | --- | --- | --- |
| Select Columns | Optional | string | A comma-separated list of fields to query. It should include necessary attributes, segments, and metrics. |
| From Target | Optional | string | The target resource name. It will be used in the FROM clause of the query statement. |
| Other Conditions | Optional | string | Other conditions for the query. It will be used in the WHERE clause of the query statement. |
| Enable Date Range | Optional | boolean | Enable query by date range option. Disabling this option requires that `Other Conditions` starts with the WHERE keyword. Disabling this option also disables Incremental mode, Start Date, and End Date. |


### Define Data Settings

Optionally, you can modify advanced data settings. Select **Next** to move to the next step.

![](/assets/google-ads-import-integration-v2-2024-08-06-5.9673dac09cfdafcf311c3895320451d2e018d8e5f17d194f5c066d1649402578.7c52a81f.png)

| Parameter | Required | Type | Description |
|  --- | --- | --- | --- |
| Retry Limit | Required | int | Internal maximum retries limit. Default: 5 times. |
| Initial retry time wait in millis | Required | int | Initial retry waiting time in milliseconds. Default: 500ms. |
| Max retry wait in millis | Required | int | Maximum retry waiting time in milliseconds. Default: 300,000ms. |


### Preview Your Data

- On the `**4 - Data Preview**` step, select **Generate Preview** to see an [approximated view](https://docs.treasuredata.com/smart/project-product-documentation/previewing-your-source-data) of your data before running the import (optional)
- Select **Next** to continue


![](/assets/google-ads-import-integration-v2-2024-08-06-3.d1a7264878d399f9a4e744868a69b15ed5ab861a1fd396d9ecef55513fcc8527.7c52a81f.png)

### Data Placement

For data placement, select the target database and table where you want your data placed and indicate how often the import should run.

1. Select **Next.** Under Storage, you will create a new or select an existing database and create a new or select an existing table for where you want to place the imported data.
2. Select a **Database** > **Select an existing** or **Create New Database**.
3. Optionally, type a database name.
4. Select a **Table**> **Select an existing** or **Create New Table**.
5. Optionally, type a table name.
6. Choose the method for importing the data.
  - **Append** (default)-Data import results are appended to the table.
If the table does not exist, it will be created.
  - **Always Replace**-Replaces the entire content of an existing table with the result output of the query. If the table does not exist, a new table is created.
  - **Replace on New Data**-Only replace the entire content of an existing table with the result output when there is new data.
7. Select the **Timestamp-based Partition Key** column.
If you want to set a different partition key seed than the default key, you can specify the long or timestamp column as the partitioning time. As a default time column, it uses upload_time with the add_time filter.
8. Select the **Timezone** for your data storage.
9. Under **Schedule**, you can choose when and how often you want to run this query.


#### Run once

1. Select **Off**.
2. Select **Scheduling Timezone**.
3. Select **Create & Run Now**.


#### Repeat Regularly

1. Select **On**.
2. Select the **Schedule**. The UI provides these four options: *@hourly*, *@daily* and *@monthly* or custom *cron*.
3. You can also select **Delay Transfer** and add a delay of execution time.
4. Select **Scheduling Timezone**.
5. Select **Create & Run Now**.


After your transfer has run, you can see the results of your transfer in **Data Workbench** > **Databases.**

## Import from Google Ads via CLI (Toolbelt)

**Prerequisites:**

- TD Toolbelt: install the latest version of the TD CLI tool: [TD Toolbelt](https://toolbelt.treasuredata.com/)
- Authentication ID: follow the steps above to create an Authentication for this integration on the TD Console. Then the ID could be seen at the last portion of its URL on the Authentication screen.


![](/assets/google-ads-import-integration-v2-2024-08-06-9.fdc162a377e20998a8f41e69c38afef49bbd1ab0b84f6b913fd06fe82b2010f3.7c52a81f.png)

**General steps:**

1. Create a YML configuration file, ex: `**load.yml**`, referencing the created authentication in the `**td_authentication_id**' field.
Refer to the below [Parameter Reference](/int/google-ads-import-integration-v2#h3__1455987732) and [Example](/int/google-ads-import-integration-v2#h3_1689083776) for more details
2. Preview the input data (optional) using the command:
`$ **td connector:preview** load.yml`
3. Trigger the data import using the command:
`$ **td** **connector:issue** load.yml --database db-name --table table-name`
4. Schedule the execution using the command:
`$ **td** **connector:create** daily\_import "10 0 \* \* \*" db-name table-name load.yml`


Refer to [this page](/int/amazon-redshift-import-integration-using-the-cli) for more reference information

### Parameters Reference

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| client_customer_id | Client customer ID | String |  | True |
| login_customer_id | Ads Manager Account ID. This is required if the Ads Account is accessible via a Google Manager account. | String |  | False |
| target | Predefined report type. Used when `enable\_custom\_query` is false. | String | - ad_performance_report - adgroup_performance_report - campaign_performance_report - keywords_performance_report | False |
| segments | List of additional segments.   Used when `enable\_custom\_query` is false.  When the `date\_range` is ALL_TIME, no time segment is required  Otherwise, one type of time segment is needed.  time segment is supported: Date, Day of week, Week, Month, Quarter, Year | Array of String |  | False |
| include_predefined_metrics | Include all predefined metrics  Used when `enable\_custom\_query` is false. | Boolean | True | False |
| metrics | List of additional metrics.  Used when `enable\_custom\_query` is false. | Array of String |  | False |
| attributes | List of additional attributes.  Used when `enable\_custom\_query` is false | Array of String |  | False |
| incremental | Run the job in incremental mode | Boolean | False | False |
| incremental_duration | Duration in days for the incremental job.  Ignore end_date and recalculate it by this formula:   end_date = start_date + incremental_duration | Integer | 0 | False |
| data_range | The date range of the target data. Refer to [here](/int/google-ads-import-integration-v2#h2__1553143459) for supported values | String |  |  |
| start_date | Start date, used with `date\_range` is `custom\_date` | Date |  | False |
| end_date | End date, used with `date\_range` is `custom\_date` | Date |  | False |
| include_negative_keywords | Filter the records by negative keywords, only used with keywords_performance_report | False | False | False |
| enable_custom_query | Enable the use of custom query | Boolean | False | True |
| select_columns | List of fields to query, separated by comma | String |  | False |
| from_target | Report target name | String |  | False |
| other_conditions | The other condition of the query | String |  | False |
| enable_date_rage | Enable data range query and incremental mode | Boolean | True | False |
| td_authentication_id | The ID of an Authentication created on the TD Console | String | Enable query by date range option. Disable this option will require `Other Conditions` to start with `WHERE` keyword.  Disable this option also disable Incremental mode, Start Date, and End Date also | True |
| refresh_token | The authentication info is required, and it is more convenient to create it on the UI and then refer to its ID using the above parameter. Alternatively, you can create a Google API project to provide the credential information required for these four parameters. | String |  | False |
| client_id | String |  | False |  |
| client_secret | String |  | False |  |


### Examples

#### Disable custom query


```yaml
in:
  type: google_adwords_v2
  td_authentication_id: 330392
  enable_custom_query: false
  client_customer_id: xx-xxxx-xxxx
  target: AD_PERFORMANCE_REPORT
  date_range: "CUSTOM_DATE"
  include_predefined_metrics: false
  incremental: true
  start_date: 2020-03-01
  end_date: 2020-03-02
  segments: ["segments.date"]
  metrics: ["metrics.absolute_top_impression_percentage"]
out:
  mode: append
```

#### Enable custom query


```yaml
in:
  type: google_adwords_v2
  td_authentication_id: 330392
  enable_custom_query: true
  client_customer_id: xx-xxxx-xxxx
  date_range: "CUSTOM_DATE"
  enable_date_range: true
  incremental: true
  start_date: 2020-03-01
  end_date: 2020-03-02
  select_columns: ad_group_criterion.criterion_id, ad_group.id, ad_group.name, segments.date
  from_target: keyword_view
  other_conditions: "AND ad_group_criterion.type = 'KEYWORD'"
out:
  mode: append
```

#### Use with Manager Ads Account


```yaml
in:
  type: google_adwords_v2
  td_authentication_id: 330392
  enable_custom_query: true
  client_customer_id: xx-xxxx-xxxx
  login_customer_id: xx-xxxx-xxxx
  date_range: "CUSTOM_DATE"
  incremental: true
  start_date: 2020-03-01
  end_date: 2020-03-02
  select_columns: ad_group_criterion.criterion_id, ad_group.id, ad_group.name, segments.date
  from_target: keyword_view
  other_conditions: "AND ad_group_criterion.type = 'KEYWORD'"
out:
  mode: append
```

### Import from Google Ads V2 via Workflow

You can import data from Google Ads by using the TD Workflow. Refer [here](/int/using-td-workflow-with-td-integrations) for more detailed information.

### How to convert Google Ads Query Language to a custom query in the connector

Query language reference: [https://developers.google.com/google-ads/api/docs/query/overview?hl=en](https://developers.google.com/google-ads/api/docs/query/overview?hl=en)

Example:


```sql
SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE segments.date during LAST_30_DAYS
  AND campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id
in:        type: google_adwords_v2  enable_custom_query: true  client_id: xxx  client_secret: xxx  refresh_token: xxx  client_customer_id: xx-xxxx-xxxx  date_range: "LAST_30_DAYS"  developer_token: xxx  select_columns: campaign.id, campaign.name, campaign.status, metrics.impressions, segments.date  from_target: campaign  other_conditions: "AND campaign.status = 'PAUSED' AND metrics.impressions > 1000"
in:        type: google_adwords_v2  enable_custom_query: true  client_id: xxx  client_secret: xxx  refresh_token: xxx  client_customer_id: xx-xxxx-xxxx  login_customer_id: xx-xxxx-xxxx  date_range: "LAST_30_DAYS"  developer_token: xxx  select_columns: campaign.id, campaign.name, campaign.status, metrics.impressions, segments.date  from_target: campaign  other_conditions: "AND campaign.status = 'PAUSED' AND metrics.impressions > 1000"
```

Note: The query should have time and it should present the where condition, `other_conditions`  should start with `AND` as in the example.

### Predefined Metrics

| **Report Type** | **Predefined Metrics** |
|  --- | --- |
| Ad Performance AdGroup Performance Campaign Performance | ClicksImpressionsCtrAverageCpcCostConversionsViewThroughConversionsCostPerConversionConversionRate ConversionFromInteractionsRate |
| Keywords Performance | ClicksImpressionsCtrAverageCpcCostConversionsViewThroughConversionsCostPerConversionConversionRateAbsoluteTopImpressionPercentageTopImpressionPercentage |


### Available Date Ranges

| **Date Range** | **Description** |
|  --- | --- |
| TODAY | Today only. |
| YESTERDAY | Yesterday only. |
| LAST_7_DAYS | The last 7 days not including today. |
| LAST_WEEK | The seven-day period starting with previous Monday. |
| LAST_BUSINESS_WEEK | The 5-day business week, Monday through Friday, of the previous business week. |
| THIS_MONTH | All days in the current month. |
| LAST_MONTH | All days in the previous month. |
| ALL_TIME | The entire available time range. |
| CUSTOM_DATE | A custom date range. Need `start_date` and `end_date` in `yyyy-MM-dd`. |
| LAST_14_DAYS | The last 14 days not including today. |
| LAST_30_DAYS | The last 30 days not including today. |
| THIS_WEEK_SUN_TODAY | The period between the previous Sunday and the current day. |
| THIS_WEEK_MON_TODAY | The period between the previous Monday and the current day. |
| LAST_WEEK_SUN_SAT | The seven-day period starting with the previous Sunday. |