Google AdWords

Google AdWords allows you to replicate your Google Ads data into the desired Destination system for scalable analysis.

Note: The Google AdWords API is being deprecated on April 27, 2022. You can now use the Google Ads API to create Pipelines. Read Migrating from AdWords to Google Ads API know how you can switch over to the new API.

Read Google Ads to know about the prerequisites and initial steps to start creating your Pipeline with this Source.


Configuring Google AdWords Connection Settings

Perform the following steps to configure Google Ads as the Source in your Pipeline:

  1. Click PIPELINES in the Asset Palette.

  2. Click + CREATE in the Pipelines List View.

  3. In the Select Source Type page, select Google Ads.

  4. In the Select your Google Ads Version page, select Google AdWords.

    Select Google AdWords

  5. In the Configure your Google Ads page, click + ADD GOOGLE ADS ACCOUNT. This redirects you to the Google Ads login page.

  6. Log in to your Google Ads account.

  7. Click Allow to authorize Hevo to access your Google Ads data.

    Click Allow

  8. In the Configure your Google AdWords Source page, specify the following:

    Test&Continue

    • Pipeline Name: A unique name for the Pipeline, not exceeding 255 characters.

    • Select Accounts: The Google Ads account(s) from where you want to replicate the data.

    • Select Reports: Select one of the following report types to ingest data from your Google Ads reports.

      • Predefined Reports: Hevo automatically selects all the metrics and dimensions for each Google Ads report that you want to replicate.

        For steps to configure predefined reports, read Predefined Reports.

      • Custom Reports: Hevo allows you to manually select the metrics and dimensions for each Google Ads report that you want to replicate.

        For steps to configure custom reports, read Custom Reports.

    • Metadata Objects (Optional): Select the metadata objects of your Google Ads that you want to replicate. Example: ACCOUNTS, CAMPAIGNS. Default: All.

    • Historical Sync Duration: The duration for which past data must be ingested. Default: 1 Year.

  9. Click CONTINUE.

  10. Proceed to configuring the data ingestion and setting up the Destination.


Predefined Reports

In case of predefined reports, Hevo automatically selects all the metrics and dimensions for each Google Ads report that you want to replicate to your Destination system.

To configure predefined reports, specify the following Predefined Report Settings:

Predefined settings

  • Report Names: Select the check box next to each report whose data you want to replicate to the Destination system.

  • Aggregation Window: The duration for which the report’s data is aggregated. Aggregation is done on a daily basis. Default: Daily.

    • Daily: Aggregates the data present in the reports once a day daily.

    • Last 7 days: Aggregates the data present in the reports for the last 7 days on a daily basis.

    • Last 14 days: Aggregates the data present in the reports for the last 14 days on a daily basis.

    • Last 30 days: Aggregates the data present in the reports for the last 30 days on a daily basis.

  • Advanced Settings:

    • Conversion Window (in days): Specify the duration at which you want to refresh the data to capture conversions. Default: 30 days. Max value: 90. Min Value: 1.

Custom Reports

In case of custom reports, you can manually select the metrics and dimensions for each Google Ads report that you want to replicate.

To configure custom reports, specify the following Custom Report Settings:

Custom settings for Google AdWords

  • Report Name: Select the check box next to the report whose data you want to replicate to the Destination system.
    Note: The following reports do not have any segments. Therefore, these are not available for selection. To ingest data from these reports, use predefined reports.

    • call-metrics-call-details-report

    • campaign-criteria-report

    • campaign-negative-keywords-performance-report

    • campaign-negative-locations-report

    • campaign-negative-placements-performance-report

    • campaign-shared-set-report

    • click-performance-report

    • label-report

    • shared-set-criteria-report

    • shared-set-report

  • Segments: Select the criteria for organizing the data. These are displayed based on the report you select.

  • Dimensions: Select the dimension(s) you want to replicate. These are displayed based on the segments you select.

  • Metrics: Select the metric(s) you want to replicate. These are displayed based on the dimensions you select.

  • Aggregation Window: Select the duration for which the report’s data is aggregated on a daily basis. Default: Daily.

    • Daily: Aggregates the data present in the reports once a day daily.

    • Last 7 days: Aggregates the data present in the reports for the last 7 days on a daily basis.

    • Last 14 days: Aggregates the data present in the reports for the last 14 days on a daily basis.

    • Last 30 days: Aggregates the data present in the reports for the last 30 days on a daily basis.

  • Advanced Settings:

    • Conversion Window (in days): Specify the duration at which you want to refresh the data to capture conversions. Default: 30 days. Max value: 90. Min Value: 1.

Data Replication

Default Pipeline Frequency Minimum Pipeline Frequency Maximum Pipeline Frequency Custom Frequency Range (Hrs)
1 Hr 15 Mins 24 Hrs 1-24

Note: The custom frequency must be set in hours, as an integer value. For example, 1, 2, 3 but not 1.5 or 1.75.

  • Historical Data: Hevo loads all the metadata objects once the Pipeline is created.

    • For Pipelines created before Release 1.63: Historical data for one year is ingested.

    • For Pipelines created after Release 1.63: Historical data for one year is ingested by default but can be changed as per the user’s requirement.

  • Incremental Data: Once the historical data ingestion is complete, every subsequent run of the Pipeline fetches new and updated data for the selected reports.

  • 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

Note: All the amount fields in the reports are listed in Micros. See sample reports:

Hevo uses the following schema to upload the records in the Destination:

  • Primary Keys for Metadata Objects

    Object Primary Key
    ACCOUNTS CustomerId
    ADS AdGroupId, Id, CustomerId
    AD_GROUPS Id, CustomerId
    CAMPAIGNS Id, CustomerId
  • Primary Keys for Reports

    Report Primary Key
    KEYWORDS_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    AD_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    URL_PERFORMANCE_REPORT Url, CriteriaParameters, Date, ExternalCustomerId
    ADGROUP_PERFORMANCE_REPORT AdGroupId, Date, ExternalCustomerId
    CAMPAIGN_PERFORMANCE_REPORT CampaignId, Date, ExternalCustomerId
    ACCOUNT_PERFORMANCE_REPORT AccountDescriptiveName, Date, ExternalCustomerId
    GEO_PERFORMANCE_REPORT CampaignId, MostSpecificCriteriaId, Date, ExternalCustomerId
    SEARCH_QUERY_PERFORMANCE_REPORT Query, Date, ExternalCustomerId
    AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT Domain, Date, ExternalCustomerId
    CAMPAIGN_NEGATIVE_KEYWORDS_PERFORMANCE_REPORT Campaign Id, Id, Date, ExternalCustomerId
    CAMPAIGN_NEGATIVE_PLACEMENTS_PERFORMANCE_REPORT Campaign Id, Id, Date, ExternalCustomerId
    SHARED_SET_REPORT SharedSetId, Date, ExternalCustomerId
    CAMPAIGN_SHARED_SET_REPORT CampaignId, SharedSetId, Date, ExternalCustomerId
    SHARED_SET_CRITERIA_REPORT SharedSetId, Id, Date, ExternalCustomerId
    CREATIVE_CONVERSION_REPORT CriterionId, AdGroupId, Date, ExternalCustomerId
    CALL_METRICS_CALL_DETAILS_REPORT AdGroupId, ExternalCustomerId, CallStartTime, Date
    KEYWORDLESS_QUERY_REPORT CriterionId, Date, ExternalCustomerId
    KEYWORDLESS_CATEGORY_REPORT Category0, Category1, Category2, Date, ExternalCustomerId
    CRITERIA_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    CLICK_PERFORMANCE_REPORT GclId, Date, ExternalCustomerId
    BUDGET_PERFORMANCE_REPORT BudgetId, Date, ExternalCustomerId
    BID_GOAL_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    DISPLAY_KEYWORD_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    PLACEHOLDER_FEED_ITEM_REPORT AdGroupId, AdId, FeedId, FeedItemId, Date, ExternalCustomerId
    PLACEMENT_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    CAMPAIGN_NEGATIVE_LOCATIONS_REPORT Campaign Id, Id, Date, ExternalCustomerId
    GENDER_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    AGE_RANGE_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    CAMPAIGN_LOCATION_TARGET_REPORT Id, Date, ExternalCustomerId
    CAMPAIGN_AD_SCHEDULE_TARGET_REPORT Id, Date, ExternalCustomerId
    PAID_ORGANIC_QUERY_REPORT AdGroupId, CampaignId, KeywordId, Date, ExternalCustomerId
    AUDIENCE_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    DISPLAY_TOPICS_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    USER_AD_DISTANCE_REPORT CampaignId, DistanceBucket, Date, ExternalCustomerId
    SHOPPING_PERFORMANCE_REPORT OfferId, Date, ExternalCustomerId
    PRODUCT_PARTITION_REPORT Id, Date, ExternalCustomerId
    PARENTAL_STATUS_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    PLACEHOLDER_REPORT AdGroupId, ExtensionPlaceholderCreativeId, Date, ExternalCustomerId
    AD_CUSTOMIZERS_FEED_ITEM_REPORT FeedItemId, Date, ExternalCustomerId
    LABEL_REPORT LabelId, Date, ExternalCustomerId
    FINAL_URL_REPORT EffectiveFinalUrl, Date, ExternalCustomerId
    VIDEO_PERFORMANCE_REPORT AdGroupId, CampaignId, CreativeId, VideoChannelId, VideoId, Date, ExternalCustomerId
    TOP_CONTENT_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    CAMPAIGN_CRITERIA_REPORT CampaignId, Id, Date, ExternalCustomerId
    CAMPAIGN_GROUP_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    LANDING_PAGE_REPORT UnexpandedFinalUrlString, Date, ExternalCustomerId
    MARKETPLACE_PERFORMANCE_REPORT CampaignId, AdGroupId, Date, ExternalCustomerId
  • As of Hevo Release 1.45, the data type of the __hevo_report_date field is changed to timestamp from the earlier type of long to make it easier to query by. This change is applicable to all Pipelines created from Release 1.45 onwards.

    Data type of 'hevo_report_date' field as 'timestamp'

  • Metadata Objects: Hevo attaches the following fields to all the metadata object Events fetched from Google APIs:

    • __hevo_report_date: The starting date of the time period for which the report is generated. If the aggregation window is 7 and the report data is generated for May 9 to May 15, then the __hevo_report_date is May 9.

    • __hevo_id: The unique ID of the Google Ads Event. Hevo derives this by hashing Google Ads data’s primary key columns.

  • Reports: Hevo attaches the following fields to all the report Events ingested from Google APIs:

    • __hevo_report_date: The starting date of the time period for which the report is generated. If the aggregation window is 7 and the report data is generated for May 9 to May 15, then the __hevo_report_date is May 9.

    • __hevo_id: The unique id of the Google Ads Event. Hevo derives this by hashing Google Ads data’s primary key columns along with __hevo_report_date and customer_id.

      Example: For the metadata object KEYWORDS_PERFORMANCE_REPORT, __hevo_id is generated using AdGroupId, Id, __hevo_report_date, and ExternalCustomerId. Thereby, Hevo ensures that if another record gets replicated with the same AdGroupId, Id, ExternalCustomerId, and __hevo_report_date, it is considered as an update to the Destination table.

  • Event Types:

    • The name of the Event Type is derived based on the aggregation window selected for the report.

      For example, if the selected report is AD_PERFORMANCE_REPORT and the aggregation window is Last 7 days, then the Event Type is named ad_performace_report_last_7_days.

      If the selected aggregation window is Daily, then the Event Type is named without any suffix.

      For example, if the selected report is AD_PERFORMANCE_REPORT and the aggregation window is Daily, then the Event Type is named ad_performance_report.

    • If you have selected a custom report, then the name of the Event Type is derived by adding the suffix __custom to the report name.

    • Some metrics can have values of different data types. For example, queryable and metadata information. For such metrics, Hevo adds a metadata column to the Destination to preserve the meta information.

    For example: if the value of the metric cost is auto:1000, Hevo would create two columns: cost and cost meta with values 1000 and auto: respectively.

    The following are some more examples where Hevo creates an additional metadata column to preserve the meta information:

    Actual Value Queryable Value Meta Information
    10% 10 %
    <10% 10 <%
    >10% 10 >%
    auto:x x auto:
    auto null auto
    10,000.5 10000.5 ,

Data Model

Hevo provides support for replicating following metadata objects and reports:

Objects

  • Accounts

  • Ad Campaigns

  • Ad Groups

  • Ads

Reports


Source Considerations

  • MySQL and Postgres Destination: For Account, AdGroups, Ads, and Ad Campaign objects, if the table or column name exceeds the maximum limit of 64 characters, Hevo maps them to a shortened name as mandated by Google. Refer to this list for shortened names mapping.

  • Google Ads does not support custom metrics and custom dimensions in the reports.


Limitations

  • Hevo currently does not support replication of the following dimensions:

    • ConversionAdjustment

    • IsNegative

    • CurrencyCode

    • ProductTitle

    • StoreId


Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Feb-21-2022 1.82 Updated the page to reflect changes due to the new Google Ads API being introduced to replace Google AdWords.
Jan-03-2022 1.79 Added information about reverse historical load in the Data Replication section.
Oct-25-2021 NA Added the Pipeline frequency information in the Data Replication section.
Aug-8-2021 NA Added a note in the Schema and Primary Keys section about fields in tables being reported in Micros.
Jul-26-2021 NA Added a note in the Overview section about Hevo providing a fully-managed Google BigQuery Destination for Pipelines created with this Source.
May-19-2021 1.63 - Updated the content to reflect the latest UI and functionality.
- Added the section, Custom Reports.
Last updated on 28 Apr 2022