Google Ads - Ad Groups

📖 Overview

The Ad Groups module manages ad groups within campaigns, including listing, fetching details, and retrieving performance metrics. Ad groups contain ads and keywords, providing organizational structure within campaigns.

Source Files:

• Controller: external/Integrations/GoogleAds/Controllers/Adgroups/AdGroupController.js
• Model: external/Integrations/GoogleAds/Models/Adgroups/AdGroupModel.js
• Routes: external/Integrations/GoogleAds/Routes/adgroups.js

🔧 API Endpoints

GET /adgroups - List Ad Groups

Parameters:

Parameter	Type	Required	Description
clientID	String	✅	Client customer ID
managerID	String	✅	Manager customer ID
campaignID	String	❌	Comma-separated campaign IDs
adGroupID	String	❌	Comma-separated ad group IDs
campaignType	Enum	❌	Campaign type filter
fromDate	String	❌	Start date (YYYY-MM-DD)
endDate	String	❌	End date (YYYY-MM-DD)
date	String	❌	Single date
searchText	String	❌	Search by name
sortField	String	❌	Sort field
sortOrder	String	❌	ASC/DESC
pageSize	Number	❌	Results per page
pageToken	String	❌	Pagination token

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    ad_groups: [
      {
        id: "456789123",
        name: "Summer Shoes Ad Group",
        campaign_id: "123456789",
        campaign_name: "Summer Sale Campaign",
        status: "ENABLED",
        type: "SEARCH_STANDARD",
        cpc_bid_micros: 2500000, // $2.50
        target_cpa_micros: 10000000, // $10.00
        ad_rotation_mode: "OPTIMIZE"
      }
    ],
    total_results: 45,
    page_token: "next_page"
  }
}

GET /adgroups/show - Get Single Ad Group

Parameters:

• clientID, managerID, adGroupID (all required)

Response: Single ad group object with full details

GET /adgroups/metrics - Ad Group Metrics

Parameters: Same as /adgroups (date range recommended)

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    ad_groups: [
      {
        id: "456789123",
        name: "Summer Shoes Ad Group",
        campaign_name: "Summer Sale Campaign",
        status: "ENABLED",
        metrics: {
          impressions: 45000,
          clicks: 2250,
          ctr: 0.05,
          cost_micros: 15000000, // $15.00
          average_cpc: 6666, // $0.0067
          conversions: 45,
          conversion_rate: 0.02,
          cost_per_conversion: 333333, // $0.33
          quality_score: 7.5
        }
      }
    ]
  }
}

🔧 Business Logic

GAQL Query Structure:

SELECT
  ad_group.id,
  ad_group.name,
  ad_group.campaign,
  ad_group.status,
  ad_group.type,
  ad_group.cpc_bid_micros,
  ad_group.target_cpa_micros,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM ad_group
WHERE campaign.id IN (${campaignIDs})
  AND segments.date BETWEEN '${fromDate}' AND '${endDate}'

Ad Group Types:

• SEARCH_STANDARD - Standard search ad group
• DISPLAY_STANDARD - Standard display ad group
• SHOPPING_PRODUCT_ADS - Shopping product ads
• VIDEO_BUMPER - Video bumper ads
• VIDEO_TRUE_VIEW_IN_STREAM - TrueView in-stream ads

Ad Group Status:

• ENABLED - Active
• PAUSED - Paused
• REMOVED - Removed

⚠️ Important Notes

• 🔐 Hierarchy: Campaign → Ad Group → Ads/Keywords
• 💰 Bids: CPC bids in micros (divide by 1,000,000)
• 📊 Metrics: Aggregated from ads and keywords within group
• 🎯 Targeting: Ad groups define targeting criteria
• 🔗 Campaign Filter: Usually filter by campaign ID for relevant results

🔗 Related Documentation

• Campaigns
• Ads
• Keywords
• Google Ads Ad Group Docs