Google Ads Integration for Nodus
1. Introduction to the Google Ads Integration
What Is This Integration?
The Google Ads integration connects your Google Ads advertising platform data with Nodus, allowing you to extract, analyze, and transform campaign performance metrics, ad insights, and keyword analytics. This integration functions as a source connector, bringing your Google Ads data into the Nodus ecosystem for advanced analytics and business intelligence.
Prerequisites:
- An active Google Ads account (standard or manager account)
- Google Ads Customer ID
- Login Customer ID (required if your account is managed by a Google Ads Manager Account)
- Appropriate access permissions to the Google Ads account
- Google account with access to your Google Ads account for OAuth authentication
Connection Overview:
The integration uses Google Ads API to extract advertising data and performance metrics. Authentication is handled through OAuth 2.0 with Google, and the connector can extract data based on predefined templates or custom GAQL (Google Ads Query Language) queries.
2. Platform Setup Documentation (Setup Form for Google Ads)
Purpose & Scope
This section covers how to set up the initial connection between Nodus and Google Ads by providing the necessary authentication credentials and account identifiers.
Field-by-Field Breakdown:
Integration Name
- Field Name & Label: Integration Name
- Description & Purpose: A descriptive name to identify this Google Ads integration within your Nodus account.
- Validation Rules & Format: Text string, required field.
- Examples: "Google Ads - Main Account", "Marketing Team Google Ads"
- Troubleshooting Tips: Use a descriptive name that clearly identifies the specific Google Ads account or purpose.
Google Ads Customer ID
- Field Name & Label: Google Ads Customer ID
- Description & Purpose: The unique identifier for your Google Ads account, used to access campaign data.
- Validation Rules & Format: Numeric string without dashes, required field.
- Examples: "1234567890"
- Troubleshooting Tips: You can find your Customer ID in the top right corner of your Google Ads interface, next to your account name. It's a 10-digit number.
Google Ads Login Customer ID
- Field Name & Label: Google Ads Login Customer ID
- Description & Purpose: The Customer ID of the manager account (MCC) if your account is managed by one.
- Validation Rules & Format: Numeric string without dashes, required field.
- Examples: "9876543210"
- Troubleshooting Tips: Only input a Login Customer ID if your Ad Account belongs to a larger Management Account (MCC). If not, enter the same value as Customer ID.
External Link
- Link Label: "Locate Your Account ID"
- URL: https://support.google.com/google-ads/answer/1704344?hl=en
- Purpose: Helps users locate their Google Ads Customer ID in the Google Ads interface.
Step-by-Step Guide:
- Log in to your Google Ads account
- Locate your Customer ID in the top right corner of the Google Ads interface
- If your account is part of a Google Ads Manager Account, locate the Manager Account Customer ID as well
- Enter your Customer ID, Login Customer ID (if applicable), and a meaningful Integration Name in the Nodus setup form
- Click Authorize to launch the Google OAuth authentication flow
- Grant permissions when prompted by Google
- Verify connection and save the configuration
Reference Links:
3. Extraction/Query Configuration (Extraction Form for Google Ads)
Purpose & Overview
This section explains how to configure data extraction from Google Ads. The platform offers various templates for extracting different types of advertising data and performance reports, as well as the ability to write custom GAQL queries.
Template & Field Documentation:
Template Selection
- Field Name & Label: Select a template
- Description & Purpose: Defines which type of Google Ads data to extract
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- Ad Dimensions Template - Metadata about ads including titles, descriptions, and creative attributes
- Ad Dimensions Metadata Template - Additional metadata for ads
- Ad Performance Template - Performance metrics for ads including impressions, clicks, and conversions
- Asset Dimensions Template - Metadata about ad assets
- Asset Performance Template - Performance metrics for ad assets
- Campaign Dimensions Template - Campaign configuration data including status, type, and budget settings
- Campaign Dimensions Metadata Template - Additional metadata for campaigns
- Campaign Performance Template - Performance metrics aggregated at the campaign level
- Keyword Performance Template - Performance data for individual keywords including quality scores
- Source of Truth Template - Core account data for reference
- UAC Performance Template - Performance data for Universal App Campaigns
Lookback Range
- Field Name & Label: Lookback Range
- Description & Purpose: Specifies how many days back to extract data
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- 3-day Range
- 7-day Range
- 28-day Range (recommended)
- 90-day Range (Optimal if 90-day DDA is used)
- Troubleshooting Tips: Larger date ranges may result in longer processing times. Some metrics may have limitations on historical data retrieval.
Historic Date Selection
- Field Name & Label: Historic Date
- Description & Purpose: For historical data extraction, specifies a custom date range
- Validation Rules & Format: Date picker, required field
- Troubleshooting Tips: Google Ads typically maintains historical data but older data may have limitations. Very old data might not be available through the API.
Custom GAQL Query Editor
- Field Name & Label: Code Editor
- Description & Purpose: Allows writing custom Google Ads Query Language (GAQL) queries for specialized data extraction needs
- Validation Rules & Format: Text editor that validates GAQL syntax
- Examples:
SELECT
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS - Troubleshooting Tips: Test your query in the Google Ads Query Builder before using it in Nodus.
Workflow & Examples:
- Select the appropriate template (e.g., "Campaign Performance Template" for campaign-level metrics)
- Choose a lookback period or specific historic date range
- Preview the query to confirm configuration
- Execute extraction
Example Use Cases:
Campaign Performance Analysis:
- Template: Campaign Performance Template
- Metrics: Impressions, clicks, spend, conversions
- Lookback: 28-day Range
Keyword Optimization:
- Template: Keyword Performance Template
- Metrics: Clicks, conversions, quality score, average position
- Lookback: 90-day Range
Ad Creative Analysis:
- Template: Ad Dimensions + Ad Performance templates (as a package)
- Metrics: Ad creative details with performance metrics
- Lookback: 28-day Range
Custom Reporting:
- Using the Code Editor to write custom GAQL queries for specialized reporting needs
- Extracting specific combinations of dimensions and metrics not available in standard templates
4. Underlying Models for Google Ads
Data Model Overview
The Google Ads API returns structured data based on the selected template or custom GAQL query. Each template corresponds to specific report types and data structures within the Google Ads API.
Schema & Field Mapping
Data Mapping & Underlying Models for Google Ads
Schema & Field Mapping
Ad Dimensions Schema
| Field | Description |
|---|---|
| ad_group_ad_ad_app_ad_descriptions | List of descriptions for app ads |
| ad_group_ad_ad_app_ad_headlines | List of headlines for app ads |
| ad_group_ad_ad_app_ad_images | List of images for app ads |
| ad_group_ad_ad_app_ad_youtube_videos | List of YouTube videos for app ads |
| ad_group_ad_ad_call_ad_business_name | Business name for call ads |
| ad_group_ad_ad_call_ad_description1 | First description for call ads |
| ad_group_ad_ad_call_ad_description2 | Second description for call ads |
| ad_group_ad_ad_call_ad_headline1 | First headline for call ads |
| ad_group_ad_ad_call_ad_headline2 | Second headline for call ads |
| ad_group_ad_ad_call_ad_path1 | First path component for call ads |
| ad_group_ad_ad_call_ad_path2 | Second path component for call ads |
| ad_group_ad_ad_demand_gen_carousel_ad_business_name | Business name for demand generation carousel ads |
| ad_group_ad_ad_demand_gen_carousel_ad_call_to_action_text | Call to action text for demand generation carousel ads |
| ad_group_ad_ad_demand_gen_carousel_ad_carousel_cards | JSON object containing carousel cards |
| ad_group_ad_ad_demand_gen_carousel_ad_description | JSON object with descriptions for demand generation carousel ads |
| ad_group_ad_ad_demand_gen_carousel_ad_headline | JSON object with headlines for demand generation carousel ads |
| ad_group_ad_ad_demand_gen_carousel_ad_logo_image | JSON object with logo image for demand generation carousel ads |
| ad_group_ad_ad_demand_gen_multi_asset_ad_business_name | Business name for demand generation multi-asset ads |
| ad_group_ad_ad_demand_gen_multi_asset_ad_call_to_action_text | Call to action text for demand generation multi-asset ads |
| ad_group_ad_ad_demand_gen_multi_asset_ad_descriptions | List of descriptions for demand generation multi-asset ads |
| ad_group_ad_ad_demand_gen_multi_asset_ad_headlines | List of headlines for demand generation multi-asset ads |
| ad_group_ad_ad_display_url | Display URL shown in the ad |
| ad_group_ad_ad_expanded_dynamic_search_ad_description | Description for expanded dynamic search ads |
| ad_group_ad_ad_expanded_dynamic_search_ad_description2 | Second description for expanded dynamic search ads |
| ad_group_ad_ad_expanded_text_ad_description | Description for expanded text ads |
| ad_group_ad_ad_expanded_text_ad_description2 | Second description for expanded text ads |
| ad_group_ad_ad_expanded_text_ad_headline_part1 | First headline part for expanded text ads |
| ad_group_ad_ad_expanded_text_ad_headline_part2 | Second headline part for expanded text ads |
| ad_group_ad_ad_expanded_text_ad_headline_part3 | Third headline part for expanded text ads |
| ad_group_ad_ad_expanded_text_ad_path1 | First path component for expanded text ads |
| ad_group_ad_ad_expanded_text_ad_path2 | Second path component for expanded text ads |
| ad_group_ad_ad_final_mobile_urls | List of final mobile URLs |
| ad_group_ad_ad_final_url_suffix | Final URL suffix |
| ad_group_ad_ad_final_urls | List of final URLs |
| ad_group_ad_ad_id | The unique identifier of the ad |
| ad_group_ad_ad_image_ad_image_url | Image URL for image ads |
| ad_group_ad_ad_image_ad_pixel_height | Pixel height for image ads |
| ad_group_ad_ad_image_ad_pixel_width | Pixel width for image ads |
| ad_group_ad_ad_name | The name of the ad |
| ad_group_ad_ad_text_ad_description1 | First description for text ads |
| ad_group_ad_ad_text_ad_description2 | Second description for text ads |
| ad_group_ad_ad_text_ad_headline | Headline for text ads |
| ad_group_ad_ad_tracking_url_template | Tracking URL template for the ad |
| ad_group_ad_ad_type | The type of ad |
| ad_group_ad_ad_url_collections | List of URL collections |
| ad_group_ad_ad_url_custom_parameters | List of URL custom parameters |
| ad_group_ad_ad_group | Ad group reference |
| ad_group_ad_status | Status of the ad (ENABLED, PAUSED, REMOVED) |
| ad_group_campaign | Campaign reference |
| ad_group_ad_rotation_mode | Ad rotation mode |
| ad_group_cpc_bid_micros | CPC bid amount in micros |
| ad_group_cpm_bid_micros | CPM bid amount in micros |
| ad_group_cpv_bid_micros | CPV bid amount in micros |
| ad_group_final_url_suffix | Final URL suffix for the ad group |
| ad_group_id | The unique identifier of the ad group |
| ad_group_name | The name of the ad group |
| ad_group_status | Status of the ad group |
| ad_group_target_cpa_micros | Target CPA in micros |
| ad_group_target_cpm_micros | Target CPM in micros |
| ad_group_target_roas | Target ROAS |
| ad_group_type | Type of ad group |
| ad_group_tracking_url_template | Tracking URL template for the ad group |
| ad_group_url_custom_parameters | URL custom parameters for the ad group |
| campaign_id | The unique identifier of the campaign |
| customer_id | The unique identifier of the customer account |
| extracted_at | Timestamp when the data was extracted |
Ad Dimensions Metadata Schema
| Field | Description |
|---|---|
| ad_group_ad_ad_final_url_suffix | Final URL suffix for the ad |
| ad_group_ad_ad_final_urls | List of final URLs for the ad |
| ad_group_ad_ad_id | The unique identifier of the ad |
| ad_group_ad_ad_tracking_url_template | Tracking URL template for the ad |
| ad_group_final_url_suffix | Final URL suffix for the ad group |
| ad_group_id | The unique identifier of the ad group |
| ad_group_tracking_url_template | Tracking URL template for the ad group |
| campaign_id | The unique identifier of the campaign |
Ad Performance Schema
| Field | Description |
|---|---|
| ad_group_ad_ad_id | The unique identifier of the ad |
| ad_group_ad_ad_name | The name of the ad |
| ad_group_id | The unique identifier of the ad group |
| ad_group_name | The name of the ad group |
| campaign_id | The unique identifier of the campaign |
| campaign_name | The name of the campaign |
| campaign_advertising_channel_sub_type | The advertising channel subtype |
| campaign_advertising_channel_type | The advertising channel type |
| customer_id | The unique identifier of the customer account |
| segments_ad_network_type | The ad network type |
| segments_date | The date for the metrics |
| metrics_impressions | Number of impressions |
| metrics_clicks | Number of clicks |
| metrics_cost_micros | Amount spent in micros |
| metrics_conversions | Number of conversions |
| metrics_conversions_value | Value of conversions |
| metrics_video_views | Number of video views |
| metrics_view_through_conversions | Number of view-through conversions |
| metrics_absolute_top_impression_percentage | Percentage of impressions shown in the absolute top position |
| metrics_all_conversions | Number of all conversions (includes non-reported conversions) |
| metrics_all_conversions_value | Value of all conversions |
| metrics_video_quartile_p25_rate | Percentage of video views that reached 25% of the video |
| metrics_video_quartile_p50_rate | Percentage of video views that reached 50% of the video |
| metrics_video_quartile_p75_rate | Percentage of video views that reached 75% of the video |
| metrics_video_quartile_p100_rate | Percentage of video views that completed the entire video |
| extracted_at | Timestamp when the data was extracted |
Campaign Dimension Schema
| Field | Description |
|---|---|
| campaign_advertising_channel_type | The main channel type (e.g., SEARCH, DISPLAY) |
| campaign_advertising_channel_sub_type | The sub-channel type |
| campaign_accessible_bidding_strategy | The accessible bidding strategy |
| campaign_app_campaign_setting_app_store | App store setting for app campaigns |
| campaign_app_campaign_setting_bidding_strategy_goal_type | Bidding strategy goal type for app campaigns |
| campaign_bidding_strategy | The bidding strategy |
| campaign_campaign_budget | The campaign budget |
| campaign_end_date | End date of the campaign |
| campaign_final_url_suffix | Final URL suffix for the campaign |
| campaign_id | The unique identifier of the campaign |
| campaign_manual_cpa | Manual CPA settings |
| campaign_manual_cpc_enhanced_cpc_enabled | Whether enhanced CPC is enabled |
| campaign_manual_cpm | Manual CPM settings |
| campaign_manual_cpv | Manual CPV settings |
| campaign_maximize_conversion_value_target_roas | Target ROAS for maximize conversion value strategy |
| campaign_maximize_conversions_target_cpa_micros | Target CPA in micros for maximize conversions strategy |
| campaign_name | The name of the campaign |
| campaign_bidding_strategy_type | The type of bidding strategy |
| campaign_serving_status | The serving status of the campaign |
| campaign_start_date | Start date of the campaign |
| campaign_status | Status of the campaign |
| campaign_target_cpa_cpc_bid_ceiling_micros | CPC bid ceiling in micros for target CPA strategy |
| campaign_target_cpa_cpc_bid_floor_micros | CPC bid floor in micros for target CPA strategy |
| campaign_target_cpa_target_cpa_micros | Target CPA in micros |
| campaign_target_impression_share_cpc_bid_ceiling_micros | CPC bid ceiling for target impression share strategy |
| campaign_target_roas_cpc_bid_ceiling_micros | CPC bid ceiling in micros for target ROAS strategy |
| campaign_target_roas_cpc_bid_floor_micros | CPC bid floor in micros for target ROAS strategy |
| campaign_target_roas_target_roas | Target ROAS value |
| campaign_tracking_url_template | Tracking URL template for the campaign |
| campaign_url_custom_parameters | URL custom parameters for the campaign |
| campaign_tracking_setting_tracking_url | Tracking URL setting |
| campaign_targeting_setting_target_restrictions | Target restrictions settings |
| campaign_target_spend_target_spend_micros | Target spend in micros |
| campaign_target_spend_cpc_bid_ceiling_micros | CPC bid ceiling in micros for target spend strategy |
| customer_tracking_url_template | Customer account tracking URL template |
| customer_final_url_suffix | Customer account final URL suffix |
| customer_id | The unique identifier of the customer account |
| extracted_at | Timestamp when the data was extracted |
Campaign Dimension Metadata Schema
| Field | Description |
|---|---|
| campaign_final_url_suffix | Final URL suffix for the campaign |
| campaign_id | The unique identifier of the campaign |
| campaign_tracking_url_template | Tracking URL template for the campaign |
| customer_tracking_url_template | Customer account tracking URL template |
| customer_final_url_suffix | Customer account final URL suffix |
Campaign Performance Schema
| Field | Description |
|---|---|
| campaign_id | The unique identifier of the campaign |
| campaign_name | The name of the campaign |
| campaign_advertising_channel_sub_type | The advertising channel subtype |
| campaign_advertising_channel_type | The advertising channel type |
| customer_id | The unique identifier of the customer account |
| segments_ad_network_type | The ad network type |
| segments_date | The date for the metrics |
| metrics_impressions | Number of impressions |
| metrics_clicks | Number of clicks |
| metrics_cost_micros | Amount spent in micros |
| metrics_conversions | Number of conversions |
| metrics_conversions_value | Value of conversions |
| metrics_video_views | Number of video views |
| metrics_view_through_conversions | Number of view-through conversions |
| metrics_absolute_top_impression_percentage | Percentage of impressions shown in the absolute top position |
| metrics_all_conversions | Number of all conversions |
| metrics_all_conversions_value | Value of all conversions |
| metrics_search_absolute_top_impression_share | Share of absolute top impressions for search campaigns |
| metrics_search_click_share | Share of clicks for search campaigns |
| metrics_search_impression_share | Share of impressions for search campaigns |
| metrics_search_top_impression_share | Share of top impressions for search campaigns |
| metrics_video_quartile_p25_rate | Percentage of video views that reached 25% of the video |
| metrics_video_quartile_p50_rate | Percentage of video views that reached 50% of the video |
| metrics_video_quartile_p75_rate | Percentage of video views that reached 75% of the video |
| metrics_video_quartile_p100_rate | Percentage of video views that completed the entire video |
| extracted_at | Timestamp when the data was extracted |
Keyword Performance Schema
| Field | Description |
|---|---|
| keyword_view_resource_name | The resource name of the keyword view |
| ad_group_criterion_keyword_text | The keyword text |
| ad_group_id | The unique identifier of the ad group |
| ad_group_criterion_negative | Whether this is a negative keyword |
| ad_group_criterion_type | The type of criterion |
| ad_group_criterion_keyword_match_type | The match type (EXACT, PHRASE, BROAD) |
| segments_ad_network_type | The ad network type |
| segments_date | The date for the metrics |
| metrics_impressions | Number of impressions |
| metrics_clicks | Number of clicks |
| metrics_cost_micros | Amount spent in micros |
| metrics_conversions | Number of conversions |
| metrics_conversions_value | Value of conversions |
| metrics_video_views | Number of video views |
| metrics_view_through_conversions | Number of view-through conversions |
| metrics_absolute_top_impression_percentage | Percentage of impressions shown in the absolute top position |
| metrics_all_conversions | Number of all conversions |
| metrics_all_conversions_value | Value of all conversions |
| metrics_search_absolute_top_impression_share | Share of absolute top impressions for search campaigns |
| metrics_search_click_share | Share of clicks for search campaigns |
| metrics_search_impression_share | Share of impressions for search campaigns |
| metrics_search_top_impression_share | Share of top impressions for search campaigns |
| metrics_video_quartile_p25_rate | Percentage of video views that reached 25% of the video |
| metrics_video_quartile_p50_rate | Percentage of video views that reached 50% of the video |
| metrics_video_quartile_p75_rate | Percentage of video views that reached 75% of the video |
| metrics_video_quartile_p100_rate | Percentage of video views that completed the entire video |
| extracted_at | Timestamp when the data was extracted |
Asset Dimension Schema
| Field | Description |
|---|---|
| asset_group_final_urls | List of final URLs for the asset group |
| asset_group_id | The unique identifier of the asset group |
| campaign_bidding_strategy | The bidding strategy of the campaign |
| campaign_campaign_budget | The campaign budget |
| campaign_bidding_strategy_type | The type of bidding strategy |
| campaign_final_url_suffix | Final URL suffix for the campaign |
| campaign_id | The unique identifier of the campaign |
| campaign_name | The name of the campaign |
| campaign_tracking_url_template | Tracking URL template for the campaign |
| campaign_url_custom_parameters | URL custom parameters for the campaign |
| customer_final_url_suffix | Customer account final URL suffix |
| customer_id | The unique identifier of the customer account |
| customer_time_zone | Time zone of the customer account |
| customer_tracking_url_template | Customer account tracking URL template |
| extracted_at | Timestamp when the data was extracted |
Asset Performance Schema
| Field | Description |
|---|---|
| asset_group_campaign | Campaign reference for the asset group |
| asset_group_id | The unique identifier of the asset group |
| asset_group_name | The name of the asset group |
| asset_group_status | Status of the asset group |
| asset_group_final_urls | List of final URLs for the asset group |
| asset_group_final_mobile_urls | List of final mobile URLs for the asset group |
| asset_group_ad_strength | Ad strength rating for the asset group |
| asset_group_primary_status | Primary status of the asset group |
| campaign_id | The unique identifier of the campaign |
| segments_date | The date for the metrics |
| metrics_clicks | Number of clicks |
| metrics_all_conversions_value | Value of all conversions |
| metrics_all_conversions | Number of all conversions |
| metrics_cost_micros | Amount spent in micros |
| metrics_impressions | Number of impressions |
| metrics_view_through_conversions | Number of view-through conversions |
| metrics_conversions_value | Value of conversions |
| metrics_conversions | Number of conversions |
| metrics_interactions | Number of interactions |
| metrics_revenue_micros | Revenue in micros |
| extracted_at | Timestamp when the data was extracted |
Source of Truth Schema
| Field | Description |
|---|---|
| customer_id | The unique identifier of the customer account |
| customer_manager | The manager account ID |
| segments_date | The date for the metrics |
| metrics_clicks | Number of clicks |
| metrics_cost_micros | Amount spent in micros |
| metrics_impressions | Number of impressions |
| extracted_at | Timestamp when the data was extracted |
5. Troubleshooting & FAQs for Google Ads
Common Issues & Error Messages
Authentication Failures
- Error: "Authentication failed" or "Invalid OAuth token"
- Solution: Re-authorize the integration through Google OAuth. Google OAuth tokens have limited lifetimes and may need to be refreshed.
Permission Issues
- Error: "Insufficient permissions" or "Access denied"
- Solution: Ensure the Google account used for authentication has appropriate access to the Google Ads account. You may need to adjust permissions in Google Ads.
Customer ID Issues
- Error: "Invalid customer ID" or "Customer not found"
- Solution: Verify that your Customer ID is correct. Make sure to enter the ID without dashes or special characters.
Login Customer ID Issues
- Error: "Invalid login customer ID"
- Solution: If your account is part of a Manager Account, ensure the Login Customer ID is correct. If your account is not part of a Manager Account, the Login Customer ID should be the same as your Customer ID.
GAQL Query Errors
- Error: "Invalid GAQL query" or "Field not found"
- Solution: Validate your GAQL query syntax. Ensure all fields referenced in the query are available for the entity type. Test your query in the Google Ads Query Builder.
Missing Data
- Common Causes:
- Date range outside of data retention period
- Insufficient account activity to generate data
- Solution: Adjust template filters, check date ranges, verify account has active campaigns
Contact & Support Information
- Nodus Support: support@nodus.com
Manager vs. Client Accounts
- Manager Accounts (MCC): Umbrella accounts that can access and manage multiple client accounts. If you're using a Manager Account, enter its Customer ID as the Login Customer ID.
- Client Accounts: Standard Google Ads accounts focused on campaign management and ad operations.
Data Retention & Limitations
- Google Ads typically retains report data for several years
- Some report types have specific data retention policies
- Daily reporting is the most granular time period available for most report types
- Performance data is generally available up to the previous day, not real-time
- Universal App Campaigns have limited reporting capabilities compared to standard campaigns