Google Ads Source

Google Ads is an online advertising service developed by Google. With Google Ads, you can take advantage of online advertising to improve your internet marketing effectiveness. Visit Website

Google Ads is an Object Cloud Source which can export data from its third party tool and import it directly into your Segment warehouse.

This document was last updated on August 13, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

  1. From your workspace’s /sources page, click Add Source.

  2. Choose Google Ads and click Connect.

  3. Click Authenticate Google Ads and go through the authentication flow.

  4. Select a Google Ads account to sync and click Next

  5. Finally, choose a schema name. This will be the namespace you will be querying against in your warehouse. We recommend choosing a name that reflects the source itself, like google_ads, or google_ads_usa.

Permissions

When setting up your Google Ads Source, you may notice that we don’t list all Google Ads accounts your Google user can view. This is because Google Ads API does not expose a list of “managed” or sub-accounts to non-administrator via the API. That said, if you have read permissions to the account, you can enter your Google Ads Customer ID directly. For more information about finding your Google Ads Customer ID, see here.

What Google Ads MCC do you sync?

By default, we sync the “primary” Google Ads account connected to your Google account, but if you’d like to override this, you can specify an Google Ads Customer ID in settings.

I’m getting an Internal Server Error!

If you’re getting the error pictured below, try disabling any ad block extensions in your browser and attempting again. We find this typically resolves the setup problems.

Components

Sync

The Google Ads source is built with a sync component, which means we’ll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we’ll grab all theobjects (and their corresponding properties) according to the Collections Table below. The objects will be written into a separate schema, corresponding to the source instance’s schema name you designated upon creation. For example, if you went with google-ads, the ads collection will be accessible at google-ads.ads in SQL.

Our sync component uses an upsert API, so the data in your warehouse loaded via sync will reflect the latest state of the corresponding resource in Google Ads. For example, if budget from 0 to 100 between syncs, on its next sync that tickets status will be 100.

The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.

Collections

Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.

CollectionTypeDescription
ad_groupsobjectAn ad group is a set of ads that share the same daily or lifetime budget, schedule, bid type, bid info, and targeting data
ad_performance_reportobjectAd Performance Report includes all statistics aggregated at the ad level, one row per ad. We currently pull 7 days of data.
adsobjectAn ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set.
campaignsobjectA campaign is a grouping of ad sets which are organized by the same business objective.
campaign_performance_reportobjectCampaign performance reports include a daily snapshot of performance statistics per campaign. We currently pull 7 days of data.
click_performance_reportobjectClick performance Reports include stats at the click level, including both valid and invalid clicks. We currently pull 7 days of data.
search_performance_reportobjectContact us to have this collection added Search query performance Reports include statistics aggregated at the search terms level, one row per combination of search terms. We currently pull 7 days of data.
keywords_performance_reportobjectContact us to have this collection added Keywords Performance Report includes all statistics aggregated at the keyword level, one row per keyword. We currently pull 7 days of data.

Video Campaign Reports

We do not pull in “Video Campaign Reports”, since it is not supported via the Google Ads API.

Collection Properties

Below are tables outlining the properties included in the collections listed above. To see the full description of each property, please refer to the Google Ads documentation linked in each collection above.

What unit is money in?

Currency values in Google Ads are in micros, or one millionth of the smallest unit. For example, in USD, the value for campaign.budget would be in one millionth of a cent.

Ad Groups

Property NameDescription
adwords_customer_idThe 10-digit Google Ads Customer ID.
campaign_idID of the campaign with which this ad group is associated.
nameName of this ad group.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
statusStatus of this ad group.

Ad Performance Report

Property NameDescription
account_currency_codeThe currency of the Customer account.
account_descriptive_nameThe descriptive name of the Customer account.
active_view_impressionsHow often your ad has become viewable on a Display Network site.
active_view_measurabilityThe ratio of impressions that could be measured by Active View over the number of served impressions.
active_view_measurable_costThe cost of the impressions you received that were measurable by Active View.
active_view_measurable_impressionsThe number of times your ads are appearing on placements in positions where they can be seen.
active_view_viewabilityThe percentage of time when your ad appeared on an Active View enabled site (measurable impressions) and was viewable (viewable impressions).
ad_group_idThe ID of the AdGroup.
ad_idThe ID of the Ad.
adwords_customer_idThe 10-digit Google Ads Customer ID.
all_conversion_rateHow often a click on your ad resulted in a conversion.
all_conversion_valueThe total value of all of your conversions, including those that are estimated.
all_conversionsBest estimate of the total number of conversions that Google Ads drives. Includes website, cross-device, and phone call conversions.
average_costThe average amount you pay per interaction.
average_positionYour ad’s position relative to those of other advertisers.
average_time_on_siteTotal duration of all sessions (in seconds) / number of sessions.
bounce_ratePercentage of clicks where the user only visited a single page on your site.
click_assisted_conversion_valueThe total value of all conversions for which this keyword, ad, ad group, or campaign triggered assisted clicks.
click_assisted_conversionsThe total number of conversions for which this keyword, ad, ad group, or campaign contributed to one or more assisted clicks.
click_assisted_conversions_over_last_click_conversionsThe total number of conversions for which this keyword, ad, ad group, or campaign received in assisted clicks divided by the total number of conversions for which it triggered the last click.
clicksThe number of clicks.
conversion_valueThe sum of conversion values for all conversions.
conversionsThe number of conversions for all conversion actions that you have opted into optimization.
costThe sum of your cost-per-click (CPC) and cost-per-thousand impressions (CPM) costs during this period.
date_startThe date start formatted as yyyy-MM-dd.
date_stopThe date stop formatted as yyyy-MM-dd.
engagementsThe number of engagements. An engagement occurs when a viewer expands your Lightbox ad.
gmail_forwardsThe number of times your ad was forwarded to someone else as a message.
gmail_savesThe number of times someone has saved your Gmail ad to their inbox as a message.
gmail_secondary_clicksThe number of clicks to your landing page on the expanded state of Gmail ads.
impression_assisted_conversionsTotal number of conversions for which this object triggered assist impressions prior to the last click.
impressionsCount of how often your ad has appeared on a search results page or website on the Google Network.
interaction_typesThe types of interactions that are reflected in the Interactions, InteractionRate, and AverageCost columns.
interactionsThe number of interactions. An interaction is the main user action associated with an ad format–clicks for text and shopping ads, views for video ads, and so on.
value_per_all_conversionThe value, on average, of all conversions.
video_quartile_100_ratePercentage of impressions where the viewer watched all of your video.
video_quartile_25_ratePercentage of impressions where the viewer watched 25% of your video.
video_quartile_50_ratePercentage of impressions where the viewer watched 50% of your video.
video_quartile_75_ratePercentage of impressions where the viewer watched 75% of your video.
video_view_rateThe number of views your TrueView video ad receives divided by its number of impressions, including thumbnail impressions for TrueView in-display ads.
video_viewsThe number of times your video ads were viewed.
view_through_conversionsThe total number of view-through conversions.

Ads

Property NameDescription
ad_group_idThe id of the adgroup containing this ad.
adwords_customer_idThe 10-digit Google Ads Customer ID.
final_mobile_urlsA list of final mobile landing page urls.
final_urlsA list of final landing page urls.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
statusThe status of the ad.
typeThe type of this ad.
urlUnique identifier for this instance of UrlData.

Campaigns

Property NameDescription
adwords_customer_idThe 10-digit Google Ads Customer ID.
end_dateDate the campaign ends.
nameName of this campaign.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
serving_statusServing status of the campaign.
start_dateDate the campaign begins.
statusStatus of the campaign.

Campaign Performance Report

Property NameDescription
active_view_impressionsHow often your ad has become viewable on a Display Network site.
active_view_measurabilityThe ratio of impressions that could be measured by Active View over the number of served impressions.
active_view_measurable_costThe cost of the impressions you received that were measurable by Active View.
active_view_measurable_impressionsThe number of times your ads are appearing on placements in positions where they can be seen.
active_view_viewabilityThe percentage of time when your ad appeared on an Active View enabled site (measurable impressions) and was viewable (viewable impressions).
advertising_channel_sub_typePrimary serving target for ads in the campaign.
adwords_customer_idThe 10-digit Google Ads Customer ID.
all_conversion_rateHow often a click on your ad resulted in a conversion.
all_conversion_valueThe total value of all of your conversions, including those that are estimated.
all_conversionsBest estimate of the total number of conversions that Google Ads drives. Includes website, cross-device, and phone call conversions.
amountThe daily budget.
average_costThe average amount you pay per interaction.
average_positionYour ad’s position relative to those of other advertisers.
average_time_on_siteTotal duration of all sessions (in seconds) / number of sessions.
base_campaign_idThe ID of base campaign of trial campaigns.
bounce_ratePercentage of clicks where the user only visited a single page on your site.
budget_idThe ID of the Budget.
campaign_idThe ID of the Campaign.
campaign_statusThe status of the Campaign.
campaign_trial_typeThe type of campaign. This shows if the campaign is a trial campaign or not.
click_assisted_conversion_valueThe total value of all conversions for which this keyword, ad, ad group, or campaign triggered assisted clicks.
click_assisted_conversionsThe total number of conversions for which this keyword, ad, ad group, or campaign contributed to one or more assisted clicks.
click_assisted_conversions_over_last_click_conversionsThe total number of conversions for which this keyword, ad, ad group, or campaign received in assisted clicks divided by the total number of conversions for which it triggered the last click.
clicksThe number of clicks.
conversion_valueThe sum of conversion values for all conversions.
conversionsThe number of conversions for all conversion actions that you have opted into optimization.
costThe sum of your cost-per-click (CPC) and cost-per-thousand impressions (CPM) costs during this period.
date_startThe date start formatted as yyyy-MM-dd.
date_stopThe date stop formatted as yyyy-MM-dd.
engagementsThe number of engagements. An engagement occurs when a viewer expands your Lightbox ad.
gmail_forwardsThe number of times your ad was forwarded to someone else as a message.
gmail_savesThe number of times someone has saved your Gmail ad to their inbox as a message.
gmail_secondary_clicksThe number of clicks to your landing page on the expanded state of Gmail ads.
impression_assisted_conversionsTotal number of conversions for which this object triggered assist impressions prior to the last click.
impression_reachNumber of unique cookies that were exposed to your ad over a given time period, or the special value “< 100” if the number of cookies is less than 100.
impressionsCount of how often your ad has appeared on a search results page or website on the Google Network.
interaction_typesThe types of interactions that are reflected in the Interactions, InteractionRate, and AverageCost columns.
interactionsThe number of interactions. An interaction is the main user action associated with an ad format–clicks for text and shopping ads, views for video ads, and so on.
invalid_clicksNumber of clicks Google considers illegitimate and doesn’t charge you for.
is_budget_explicitly_sharedIndicates if the budget is a shared budget (true) or specific to the campaign (false).
url_custom_parametersCustom URL parameters of the main object of this row.
value_per_all_conversionThe value, on average, of all conversions.
video_quartile_100_ratePercentage of impressions where the viewer watched all of your video.
video_quartile_25_ratePercentage of impressions where the viewer watched 25% of your video.
video_quartile_50_ratePercentage of impressions where the viewer watched 50% of your video.
video_quartile_75_ratePercentage of impressions where the viewer watched 75% of your video.
video_view_rateThe number of views your TrueView video ad receives divided by its number of impressions, including thumbnail impressions for TrueView in-display ads.
video_viewsThe number of times your video ads were viewed.
view_through_conversionsThe total number of view-through conversions.

Click Performance Report

Property NameDescription
ad_formatThe underlying media format of the ad.
ad_group_idThe ID of the AdGroup.
ad_network_type_1First level network type.
ad_network_type_2Second level network type (includes search partners).
adwords_customer_idThe 10-digit Google Ads Customer ID.
aoi_most_specific_target_idThe most specific location target.
campaign_idThe ID of the Campaign.
click_typeIndicates the click type for metric fields such as Impressions.
creative_idID of the ad.
criteria_parametersDescriptive string for the Criterion.
date_startThe date start formatted as yyyy-MM-dd.
date_stopThe date stop formatted as yyyy-MM-dd.
deviceDevice type where the impression was shown.
gcl_idThe Google Click ID.
pagePage number in search results where the ad was shown.
slotThe position of the Ad.
user_list_idThe ID of the UserList (audience).

Search Performance Report

Property NameDescription
ad_group_idThe ID of the AdGroup.
ad_group_nameThe name of the AdGroup.
ad_group_stateStatus of the ad group.
ad_idThe ID of the Ad.
adwords_customer_idThe 10-digit Google Ads Customer ID.
all_conversion_rateHow often a click on your ad resulted in a conversion.
all_conversion_valueThe total value of all of your conversions, including those that are estimated.
all_conversionsBest estimate of the total number of conversions that Google Ads drives. Includes website, cross-device, and phone call conversions.
average_costThe average amount you pay per interaction.
average_cpcThe total cost of all clicks divided by the total number of clicks received.
average_cpeThe average amount that you’ve been charged for an ad engagement.
average_cpmAverage Cost-per-thousand impressions (CPM).
average_cpvThe average amount you pay each time someone views your ad.
average_positionYour ad’s position relative to those of other advertisers.
campaign_idThe ID of the Campaign.
clicksThe number of clicks.
conversion_category_nameA category that describes the action the user will take to complete a conversion.
conversion_nameThe name of the conversion type.
conversion_rateThe number of conversions divided by total clicks that can be tracked to conversions
conversion_tracker_idID of the conversion tracker.
conversion_valueThe sum of conversion values for all conversions.
conversionsThe number of conversions for all conversion actions that you have opted into optimization.
costThe sum of your cost-per-click (CPC) and cost-per-thousand impressions (CPM) costs during this period.
cost_per_all_conversionTotal cost divided by all conversions.
cost_per_conversionThe Cost attributable to conversion-tracked clicks divided by the number of conversions.
cross_device_conversionsConversions from when a customer clicks on an Google Ads ad on one device, then converts on a different device or browser.
ctrThe number of clicks your ad receives (Clicks) divided by the number of times your ad is shown (Impressions).
dateThe date formatted as yyyy-MM-dd.
deviceDevice type where the impression was shown.
engagement_rateHow often people engage with your ad after it’s shown to them.
engagementsThe number of engagements. An engagement occurs when a viewer expands your Lightbox ad.
external_conversion_sourceThe source of conversion such as website, import from calls.
external_customer_idThe Customer ID.
final_urlFinal URL of the impressions.
impressionsCount of how often your ad has appeared on a search results page or website on the Google Network.
interaction_rateHow often people interact with your ad after it is shown to them.
interaction_typesThe types of interactions that are reflected in the Interactions, InteractionRate, and AverageCost columns.
interactionsThe number of interactions.
keyword_idThe ID of the Keyword that triggered the ad.
networkFirst level network type.
network_with_search_partnersSecond level network type (includes search partners).
original_ad_id-
queryKeyword that triggered the ad.
query_match_type_with_variantMatch type of the keyword that triggered the ad, including variants.
tracking_url_templateTracking template of the main object of this row.
value_per_all_conversionThe value, on average, of all conversions.
value_per_conversionThe total value of your conversions divided by the total number of conversions.
video_quartile_100_ratePercentage of impressions where the viewer watched all of your video.
video_quartile_25_ratePercentage of impressions where the viewer watched 25% of your video.
video_quartile_50_ratePercentage of impressions where the viewer watched 50% of your video.
video_quartile_75_ratePercentage of impressions where the viewer watched 75% of your video.
video_view_rateThe number of views your TrueView video ad receives divided by its number of impressions, including thumbnail impressions for TrueView in-display ads.
video_viewsThe number of times your video ads were viewed.
view_through_conversionsThe total number of view-through conversions.
weekThe date for the Monday of the week, formatted as yyyy-MM-dd.
yearThe year, formatted as yyyy.

Keyword Performance Report

Property NameDescription
ad_group_idThe ID of the AdGroup.
adwords_customer_idThe 10-digit Google Ads Customer ID.
all_conversion_rateHow often a click on your ad resulted in a conversion.
all_conversion_valueThe total value of all of your conversions, including those that are estimated.
all_conversionsBest estimate of the total number of conversions that Google Ads drives. Includes website, cross-device, and phone call conversions.
approval_statusApproval status of the criterion.
average_costThe average amount you pay per interaction.
average_cpcThe total cost of all clicks divided by the total number of clicks received.
average_cpmAverage Cost-per-thousand impressions (CPM).
average_cpvThe average amount you pay each time someone views your ad.
average_pageviewsAverage number of pages viewed per session.
average_positionYour ad’s position relative to those of other advertisers.
average_time_on_siteTotal duration of all sessions (in seconds) / number of sessions.
campaign_idThe ID of the Campaign.
click_assisted_conversion_valueThe total value of all conversions for which this keyword, ad, ad group, or campaign triggered assisted clicks.
click_assisted_conversionsThe total number of conversions for which this keyword, ad, ad group, or campaign contributed to one or more assisted clicks.
clicksThe number of clicks.
conversionsThe number of conversions for all conversion actions that you have opted into optimization.
cpc_bidCost per click bid.
cpc_bid_sourceSource of the CPC bid.
criteriaDescriptive string for the Criterion.
ctrThe number of clicks your ad receives (Clicks) divided by the number of times your ad is shown (Impressions).
date_startThe date start formatted as yyyy-MM-dd.
date_stopThe date stop formatted as yyyy-MM-dd.
impression_assisted_conversionsTotal number of conversions for which this object triggered assist impressions prior to the last click.
impressionsCount of how often your ad has appeared on a search results page or website on the Google Network.
keyword_idID of the main object of this row.
original_keyword_id-

Adding Destinations

Currently, Warehouses are the only supported destination for object-cloud sources.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!