From Release 2.26.3 onwards, Hevo supports Google Ads API V16, which includes enhanced reporting capabilities. We recommend that you upgrade your existing Pipelines to Google Ads API V16 before September 23, 2024, failing which the Pipelines will be paused. Refer to section, Migrating Pipelines to Google Ads API V16 to know about the updates in reports and the steps to upgrade the Pipeline.
Google Ads is an advertising platform by Google that allows businesses to create ads for their products and services. It also provides statistics for these ads to gather insights and grow your business faster.
Hevo uses the Google Ads API to ingest data from your Google Ads account and replicate it into the Destination of your choice. The Google Ads API is the next generation of Google AdWords API. It provides you with new features and improvements over the AdWords API that make it easy for you to manage large and complex accounts.
Prerequisites
-
An active Google Ads account from which data is to be ingested. Contact the administrator of your Google Ads account if you do not have access.
-
You are assigned the Team Administrator, Team Collaborator, or Pipeline Administrator role in Hevo to create the Pipeline.
Granting Access to your Google Ads Account (Optional)
Note: You can invite other users to access your Google Ads account data only if you are the administrator of the account.
-
Sign in to your Google Ads account.
-
In the top navigation bar, click Settings, and select Access and security from the drop-down.
-
In the Access and security screen, click the Users tab, and then click the Plus (
) icon.
-
In the Invite others to access… screen:
-
Specify the user’s email address associated with a Google account. The user must create a Google account if they do not have one.
-
Select the account access level. You should provide at least Read-only access.
-
-
Click Send invitation.
The invited users are displayed in the Pending invitations section. You can click Revoke in the Actions column if you need to withdraw the invitation.
After the user accepts the email invitation, you receive a notification in your account.
Configuring Google Ads as a Source
Perform the following steps to configure Google Ads as the Source in your Pipeline:
-
Click PIPELINES in the Navigation Bar.
-
Click + CREATE PIPELINE in the Pipelines List View.
-
On the Select Source Type page, select Google Ads.
-
On the Configure your Google Ads page, do one of the following:
-
Select a previously configured account and click CONTINUE.
-
Click + ADD GOOGLE ADS ACCOUNT and perform the following steps to configure an account:
-
Log in to your Google Ads account.
-
Click Allow to authorize Hevo to access your Google Ads data.
-
-
-
On the Configure your Google Ads Source page, specify the following:
-
Pipeline Name: A unique name for your Pipeline, not exceeding 255 characters.
-
Authorized User Account (Non-editable): The email address that you selected when connecting to your Google Ads account. This value is pre-filled.
-
Google Ads API Version: The API version that you want to use to ingest data from the Source. Default value: V16.
-
Ad Accounts: The Google Ads account(s) from where you want to replicate the data.
-
Select Report Type: Select one of the following report types to ingest data from your Google Ads reports:
-
Standard Reports: Hevo provides you a few reports that Google creates based on a valid combination of metrics and dimensions. These reports can be used according to your requirements, in order to replicate data from the report to your desired Destination quickly and efficiently. Refer to section, Standard Reports for steps to configure this.
-
Custom Reports: Hevo allows you to create your own reports by selecting the metrics and dimensions you need. Then, the data from these reports is replicated to your desired Destination. Refer to section, Custom Reports for steps to configure this.
-
-
-
Click CONTINUE.
-
Proceed to configuring the data ingestion and setting up the Destination.
Standard Reports
Hevo provides you with a few standard reports for ease of configuration that you can use according to your requirements. It automatically identifies the metrics and dimensions based on the Google Ads report that you select for replicating data to your desired Destination.
To configure standard reports, specify the following:
-
Report Names: The report(s) whose data you want to replicate to your Destination.
-
Aggregation Window: The duration for which the data in the report(s) is aggregated. Aggregation is done on a daily basis. Default duration: Daily.
-
Daily: Aggregates the data present in the reports once a day daily.
-
Weekly: Aggregates the data present in the reports for the last week.
-
Monthly: Aggregates the data present in the reports for the last month.
-
-
Conversion Window (in days): The duration at which you want the data to be refreshed to capture conversions.
Default duration: 90 days
Min duration: 30 days
Max duration: 90 days
Note: The conversion window in your Google Ads account remains unaffected by the conversion window that you specify in Hevo either during or post-Pipeline creation. For example, let us say you set a conversion window of 60 days in your Google Ads account, and a conversion window of 30 days in Hevo. Then, the conversion window in your Google ads account remains unaffected by the conversion window that you specified in Hevo.
-
Historical Sync Duration: The duration for which you want to ingest the existing data from the Source. Default duration: 1 Year.
Note: If you select All Available Data, Hevo ingests all the data available in your Google Ads account since January 01, 2011.
Note: You can only modify the Aggregation Window and Conversion Window post-Pipeline creation.
Custom Reports
Hevo allows you to create your own reports by choosing a valid combination of metrics and dimensions. You can manually select these metrics and dimensions in Hevo to replicate the data from these reports to your desired Destination.
To configure custom reports, specify the following:
-
Report Name: The report(s) whose data you want to replicate to your Destination.
-
Segments: The criteria for organizing the data retrieved from an ad campaign. These are displayed based on the report you selected above.
Note: You must always select Date from the drop-down list of Segments along with the ones that you want to use.
-
Dimensions: The categories and sub-categories to filter the data retrieved from an ad campaign, as per your requirements. These dimensions are displayed based on the Segments you selected above.
-
Metrics: The various parameters that enable you to quantitatively measure the data retrieved from an ad campaign. These metrics are displayed based on the Dimensions you selected above.
Note: Only the Metrics and Dimensions compatible with the Segments selected above are available for selection. Refer to section, Source Considerations.
-
Aggregation Window: The duration for which the data in the report(s) is aggregated. Aggregation is done on a daily basis. Default duration: Daily.
-
Daily: Aggregates the data present in the reports once a day daily.
-
Weekly: Aggregates the data present in the reports for the last week.
-
Monthly: Aggregates the data present in the reports for the last month.
-
-
Attributed & Segmenting Resources: The dimensions of the resources that you want to replicate. These are displayed based on the report you selected above.
-
Conversion Window (in days): The duration at which you want the data to be refreshed to capture conversions.
Default duration: 90 days.
Min duration: 30 days
Max duration: 90 days.
Note: The conversion window in your Google Ads account remains unaffected by the conversion window that you specify in Hevo either during or post-Pipeline creation. For example, let us say you set a conversion window of 60 days in your Google Ads account, and a conversion window of 30 days in Hevo. Then, the conversion window in your Google ads account remains unaffected by the conversion window that you specified in Hevo.
-
Historical Sync Duration: The duration for which you want to ingest the existing data from the Source. Default duration: 1 Year.
Note: If you select All Available Data, Hevo ingests all the data available in your Google Ads account since January 01, 2011.
Note: You can only modify the Aggregation Window and Conversion Window post-Pipeline creation.
Migrating Pipelines to Google Ads API V16
From Release 2.26.3 onwards, Hevo supports Google Ads API V16 in Pipelines. As a part of this upgrade, Hevo supports the following updates made to the reports:
Updates to existing reports
| Reports | Updates | |
|---|---|---|
| Attributes | Metrics | |
| Ad Group | Addition of: - ad_group.primary_status - ad_group.primary_status_reasons |
Addition of: - metrics.cross_device_conversions_value_micros |
| Ad Group Ad | Addition of: - ad_group_ad.ad.demand_gen_product_ad.breadcrumb1 - ad_group_ad.ad.demand_gen_product_ad.breadcrumb2 - ad_group_ad.ad.demand_gen_product_ad.business_name - ad_group_ad.ad.demand_gen_product_ad.call_to_action - ad_group_ad.ad.demand_gen_product_ad.description - ad_group_ad.ad.demand_gen_product_ad.headline - ad_group_ad.ad.demand_gen_product_ad.logo_image - ad_group_ad.primary_status - ad_group_ad.primary_status_reasons |
Addition of: - metrics.cross_device_conversions_value_micros |
| Asset Group Product Group View | Addition of: - metrics.cross_device_conversions_value_micros |
|
| Campaign | Addition of: - campaign.shopping_setting.disable_product_feed |
Addition of: - metrics.cross_device_conversions_value_micros |
| Customer | Addition of: - customer.video_brand_safety_suitability |
Addition of: - metrics.cross_device_conversions_value_micros |
| Keyword View | Addition of: - metrics.cross_device_conversions_value_micros |
|
| Product Group View | Addition of: - metrics.cross_device_conversions_value_micros |
|
| Shopping Performance View | Addition of: - metrics.cross_device_conversions_value_micros |
Refer to section, Data Model for a detailed description of these reports.
You can upgrade your Pipeline to use Google Ads API V16 by performing the following steps:
Note: Once the Pipeline is upgraded, it cannot be reverted to use API V15 for fetching data from your Google Ads account.
-
Click PIPELINES in the Navigation Bar.
-
Search for and click the Google Ads Source Pipeline that you want to upgrade.
-
In the banner displayed in the Pipeline Overview page, click UPGRADE PIPELINE.
-
In the confirmation dialog, click YES, UPGRADE PIPELINE.
You have successfully upgraded the Pipeline.
After upgrading, Hevo includes the newly added resources (attributes and metrics) in your reports. To fetch data for the added resources, restart the historical load for the reports.
Data Replication
| For Teams Created | Default Ingestion Frequency | Minimum Ingestion Frequency | Maximum Ingestion Frequency | Custom Frequency Range (in Hrs) |
|---|---|---|---|---|
| Before Release 2.21 | 12 Hrs | 15 Mins | 24 Hrs | 1-24 |
| After Release 2.21 | 12 Hrs | 30 Mins | 24 Hrs | 1-24 |
-
Historical Data:
-
For Pipelines created before Release 1.63: In the first run of the Pipeline, Hevo fetches the data of all the objects and reports available in your account for the past one year and loads it to the Destination. In case of the Click View report, Hevo fetches the data for the past 90 days and loads it to the Destination.
-
For Pipelines created after Release 1.63: In the first run of the Pipeline, Hevo fetches the data of all the objects and reports available in your account for the past one year and loads it to the Destination. This default duration of one year can be changed as per the user’s requirement.
From Release 1.79 onwards, Hevo ingests the historical data for all the objects using the Recent Data First approach. This enables you to have quicker access to the most recent data. This change applies to all new and existing Pipelines.
-
-
Incremental Data: Once the historical data ingestion is complete, every subsequent run of the Pipeline fetches new and updated data for the objects and reports as per the ingestion frequency.
-
Data Refresh: Hevo refreshes the data based on the specified conversion window. For example, if the conversion window is 30, Hevo refreshes the data for the last 30 days from today.
Schema and Primary Keys
Hevo uses the following schema to upload the records in the Destination database:
| Report | Primary Key |
|---|---|
| Ad Group | ad_group.resource_name |
| Ad Group Ad | ad_group_ad.resource_name |
| Ad Group Ad Asset Combination View | ad_group_ad_asset_combination_view.resource_name |
| Ad Group Ad Asset View | ad_group_ad_asset_view.resource_name |
| Ad Group Asset | ad_group_asset.resource_name |
| Ad Group Audience View | ad_group_audience_view.resource_name |
| Ad Schedule View | ad_schedule_view.resource_name |
| Age Range View | age_range_view.resource_name |
| Asset Field Type View | asset_field_type_view.resource_name |
| Asset Group Product Group View | asset_group_product_group_view.resource_name |
| Asset Set Asset | asset_set_asset.resource_name |
| Asset Set Type View | asset_set_type_view.resource_name |
| Bidding Strategy | bidding_strategy.resource_name |
| Campaign | campaign.resource_name |
| Campaign Asset | campaign_asset.resource_name |
| Campaign Audience View | campaign_audience_view.resource_name |
| Campaign Budget | campaign_budget.resource_name |
| Campaign Group | campaign_group.resource_name |
| Click View | click_view.resource_name |
| Customer | customer.resource_name |
| Customer Asset | customer_asset.resource_name |
| Customer Search Term Insight | customer_search_term_insight.resource_name |
| Detail Placement View | detail_placement_view.resource_name |
| Display Keyword View | display_keyword_view.resource_name |
| Distance View | distance_view.resource_name |
| Dynamic Search Ads Search Term View | dynamic_search_ads_search_term_view.resource_name |
| Expanded Landing Page View | expanded_landing_page_view.resource_name |
| Extension Feed Item | extension_feed_item.resource_name |
| Feed Item | feed_item.resource_name |
| Feed Placeholder View | feed_placeholder_view.resource_name |
| Gender View | gender_view.resource_name |
| Geographic View | geographic_view.resource_name |
| Group Placement View | group_placement_view.resource_name |
| Hotel Group View | hotel_group_view.resource_name |
| Hotel Performance View | hotel_performance_view.resource_name |
| Hotel Reconciliation | hotel_reconciliation.resource_name |
| Income Range View | income_range_view.resource_name |
| Keyword View | keyword_view.resource_name |
| Landing Page View | landing_page_view.resource_name |
| Location View | location_view.resource_name |
| Managed Placement View | managed_placement_view.resource_name |
| Paid Organic Search Term View | paid_organic_search_term_view.resource_name |
| Parental Status View | parental_status_view.resource_name |
| Product Group View | product_group_view.resource_name |
| Search Term View | search_term_view.resource_name |
| Shopping Performance View | shopping_performance_view.resource_name |
| Smart Campaign Search Term View | smart_campaign_search_term_view.resource_name |
| Topic View | topic_view.resource_name |
| Travel Activity Group View | travel_activity_group_view.resource_name |
| Travel Activity Performance View | travel_activity_performance_view.resource_name |
| User Location View | user_location_view.resource_name |
| Video | video.resource_name |
| Webpage View | webpage_view.resource_name |
Reports: Hevo attaches the following fields to all the report Events ingested from Google Ads API:
-
__hevo_report_<aggregation window>: The date, week, or month for which the report is generated. The name of the field depends on the aggregation window you select while configuring the Pipeline. For example:-
If you select the aggregation window as Daily, the field name is
__hevo_report_date. -
If you select aggregation window as Weekly, the field name is
__hevo_report_week. -
If you select aggregation window as Monthly, the field name is
__hevo_report_month.
-
-
__hevo_id: The unique ID of the Google Ads Event. Hevo derives this by hashing multiple fields from the standard and custom reports.
Data Model
The following is the list of tables (reports) that are created at the Destination when you run the Pipeline:
| Report | Description |
|---|---|
| Ad Group | Contains details of an ad group created in your Google Ads account. For example, its name, status, type, target customers, and the campaign to which the ad group belongs. An ad group contains one or more ads that have a common target audience. |
| Ad Group Ad | Contains details of an ad in an ad group. For example, its ID, status, and the ad group that the ad belongs to. |
| Ad Group Ad Asset View | Contains details of the performance and reach of the assets associated with an ad group ad. For example, its ID, role in the ad, and the ad to which it is associated. |
| Ad Group Ad Asset Combination View | Contains details of the various combinations of ad assets used in an ad group. This enables you to optimize the performance of your ad campaigns. |
| Ad Group Asset | Contains details of the assets associated with an ad group. For example, its ID, status, and role in the ad group. |
| Ad Group Audience View | Contains details of the performance and reach of an ad group through various resources, such as searches and or YouTube ads. This performance data is aggregated at the target audience level. |
| Ad Schedule View | Contains details of the performance and reach of an ad campaign, aggregated according to its schedule. |
| Age Range View | Contains details of the performance and reach of an ad campaign, aggregated according to the age range of its target audience. |
| Asset Field Type View | Contains details of the performance and reach of each asset that is being used as an extension. |
| Asset Group Product Group View | Contains details of the performance of product groups within an asset group. |
| Asset Set Asset | Contains details of the association between an asset and an asset set. |
| Asset Set Type View | Contains details of the performance of asset sets in campaigns. This enables you to optimize these campaigns. |
| Bidding Strategy | Contains details of the bidding strategy that you use for your campaigns. For example, it’s ID, name, status, currency, and the campaigns it is used in. A bidding strategy is when you set an average bid that you are willing to spend to maximize impressions on your campaigns. |
| Campaign | Contains details of the ad campaigns running in your account. For example, its ID, name, status, budget, and bidding strategy. An ad campaign consists of one or more ad groups that are used to advertise the products or services provided by your organization. |
| Campaign Asset | Contains details of the assets used in an ad campaign. For example, its status and role in the campaign. |
| Campaign Audience View | Contains details of the performance and reach of an ad group through various resources, such as searches and or YouTube ads. This performance data is aggregated at the target audience and campaign level. |
| Campaign Budget | Contains details of the budget that you have set for one or more campaigns. For example, it’s ID, name, amount, currency, and the number of campaigns using this budget. |
| Campaign Group | Contains details of the organization and management of your ad campaigns. This enables you to optimize strategies and better analyze performance statistics. |
| Click View | Contains details of the performance and reach of a campaign, in terms of the clicks and interactions. |
| Customer | Contains details of the users to whom you are advertising your product or service. |
| Customer Asset | Contains details of the assets available in your Google Ads account. |
| Customer Search Term Insight | Contains details of the search terms that triggered the display of your ads to an audience. |
| Detail Placement View | Contains details of the performance and reach of an ad group on the basis of location where you are advertising it, such as YouTube, website, and mobile application. |
| Display Keyword View | Contains details of the performance and reach of keywords that you use in an ad group for it to be visible to the audience on the basis of their browsing history or other details. |
| Distance View | Contains details of the performance and reach on ad groups on the basis of distance between your advertising location and the location of a customer. |
| Dynamic Search Ads Search Term View | Contains details of the performance and reach of the frequently searched terms and phrases, and how your ads are displayed when someone searches for these terms. |
| Expanded Landing Page View | Contains details of the performance and reach of an ad group on the basis of the expanded final URL. An expanded final URL is the link to the relevant page where your ad is shown to the users on the basis of their searched keywords. |
| Extension Feed Item | Contains details of the items that you want to advertise using Google Ads, along with the extension type and other additional details. An ad extension is any additional information that you show alongside your ads. |
| Feed Item | Contains details of the products or services you want to advertise using Google Ads. |
| Feed Placeholder View | Contains details of the performance and reach of the placeholders you can use for mapping a feed. |
| Gender View | Contains details of the performance and reach of an ad group on the basis of gender of the viewers. |
| Geographic View | Contains details of the performance and reach of an ad group on the basis of country. |
| Group Placement View | Contains details of the performance and reach of your ad group on the channels where they appear on YouTube or Google display network. For example, a website, a YouTube channel, or a mobile application. |
| Hotel Group View | Contains details of the performance and reach of one or more ads created in your Google Ads account to advertise your hotels. |
| Hotel Performance View | Contains details of the performance and reach of hotel groups on the basis of the clicks and impressions. |
| Hotel Reconciliation | Contains details of the reconciliation of hotel bookings to your advertisements. |
| Income Range View | Contains details of the performance and reach of an ad group on the basis of the income range of your target audience. |
| Keyword View | Contains details of the performance and reach of the words or phrases that help in displaying your ads when people search for these words. |
| Landing Page View | Contains details of the performance and reach of an ad group aggregated on the basis of the landing page unexpanded URL. An unexpanded URL does not contain any contextual keywords or other parameters that may be added to an expanded URL. |
| Location View | Contains details of the performance and reach of an ad campaign on the basis of target location. |
| Managed Placement View | Contains details of the performance and reach of the placement criteria set for targeting of ads. A placement criteria contains the internet locations where you want to display your ads. |
| Paid Organic Search Term View | Contains details of the performance of your ads against the paid and organic search terms. This enables you to optimize your ads for visibility and engagement. |
| Parental Status View | Contains details of the performance and reach of the ads rolled out targeted at users who are parents. |
| Product Group View | Contains details of the performance and reach of the groups in which your products are categorized. |
| Search Term View | Contains details of the performance and reach of an ad group on the basis of the terms searched by the users in the search network. |
| Shopping Performance View | Contains details of the performance and reach of a shopping campaign on the basis of the product characteristics, such as brand, category, and product type. |
| Smart Campaign Search Term View | Contains details of the performance and reach of the smart campaigns in your Google Ads account. A smart campaign helps draw customers to buy the products or services you are offering by highlighting the various attractive features of your business. |
| Topic View | Contains details of the performance and reach of the ads appearing on YouTube or the Google display network pages that contain the information related to your specific topics. For example, let us say your topic is goods transfer, then your ads may be listed on pages that contain information related to commercial vehicles, packing and moving, and so on. |
| Travel Activity Group View | Contains details of the performance of the travel-related campaigns containing various travel activities. This enables you to optimize your campaigns as per the travel interests of the audience. |
| Travel Activity Performance View | Contains details of the performance of each travel-related ad within your campaign. This enables you to optimize strategies and returns. |
| User Location View | Contains details of the performance and reach of your ads on the basis of the physical location of your target audience. |
| Video | Contains details of the videos that you can create to advertise your products to the target audience on YouTube or the Google display network. |
| Webpage View | Contains details of the performance and reach of your ads on the pages where they are displayed. |
Additional Information
Read the detailed Hevo documentation for the following related topics:
Source Considerations
-
Google Ads does not support custom metrics and dimensions in the reports.
-
For custom reports, you can only select the metrics and dimensions that are compatible with the segments you select. Read Segments to know more about the segments in Google Ads, and the metrics and dimensions compatible with these segments.
-
The Google Ads API does not return any Events in the report if an ad did not get any impressions. Therefore, the schema for that ad is not created in your Destination. This is because the Google Ads API does not support the includeZeroImpressions parameter.
-
The Google Ads API uses a querying approach to fetch data from your Google Ads account. Therefore, there are no readily available reports in Google Ads. Hevo aggregates the data in your Google Ads account and generates a report using the segments, dimensions, and metrics of the various resources in your account. It results in a higher number of ingestions for your Hevo Google Ads Pipeline. For example, let us say, while setting up your Pipeline in Hevo, you also set the aggregation window as last 30 days for 100 reports, and the ingestion frequency as 1 hour. Then, the number of reports ingested every 1 hour would be 30 x 100 = 3000 reports. In one day, the number of reports ingested would be 3000 x 24 = 72000 reports. As a result, the number of Events ingested per day is high.
-
Google Ads has removed support for exporting data for some Gmail-related metrics in the Ad Group Ad report in Version 12 of their API. As a result, from Release 2.09, Hevo does not support the ingestion of historical data for these metrics, and all existing Pipelines containing these metrics now load null values for these fields.
Limitations
- Hevo does not fetch data for the metrics that are not filterable by the segment,
date.
Revision History
Refer to the following table for the list of key updates made to this page:
| Date | Release | Description of Change |
|---|---|---|
| Sep-30-2024 | 2.28.1 | Updated section, Data Replication to change the default ingestion frequency to 12 Hrs. |
| Aug-19-2024 | 2.26.3 | - Removed section, Migrating Pipelines to Google Ads API V15. - Added section, Migrating Pipelines to Google Ads API V16. |
| Mar-05-2024 | 2.21 | Updated the ingestion frequency table in the Data Replication section. |
| Nov-28-2023 | 2.18 | - Added section, Migrating Pipelines to Google Ads API V15. - Updated the page to add information about Google Ads API V15. |
| Jul-21-2023 | NA | Updated the page to add information according to the latest Hevo functionality. |
| Apr-04-2023 | NA | Updated section, Configuring Google Ads as a Source to update the information about historical sync duration. |
| Mar-09-2023 | 2.09 | - Updated section, Source Considerations to add information about Google Ads not exporting data for some metrics. - Updated section, Data Model to update the links of the reports to Version 12 of the Google Ads API. |
| Jan-10-2023 | NA | Updated section, Data Model to add descriptions for reports. |
| Oct-25-2022 | 2.00 | Added the section, Granting Access to your Google Ads Account with steps to provide other users access to the Google Ads account. |
| Sep-21-2022 | NA | New document. |