Google Ads - Keywords

📖 Overview

The Keywords module manages keywords (search terms) within ad groups, including listing, fetching details, and retrieving performance metrics. Keywords determine when search ads are triggered and shown to users.

Source Files:

• Controller: external/Integrations/GoogleAds/Controllers/Keywords/KeyWordsController.js
• Model: external/Integrations/GoogleAds/Models/Keywords/KeyWordsModel.js
• Routes: external/Integrations/GoogleAds/Routes/keywords.js

🔧 API Endpoints

GET /keywords - List Keywords

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
adGroupCriterionID	String	❌	Comma-separated keyword IDs
campaignType	Enum	❌	Campaign type filter
fromDate	String	❌	Start date (YYYY-MM-DD)
endDate	String	❌	End date (YYYY-MM-DD)
searchText	String	❌	Search by keyword text

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    keywords: [
      {
        id: "321654987", // ad_group_criterion.criterion_id
        ad_group_id: "456789123",
        ad_group_name: "Summer Shoes",
        campaign_id: "123456789",
        campaign_name: "Summer Sale",
        keyword: {
          text: "summer shoes sale",
          match_type: "BROAD"
        },
        status: "ENABLED",
        cpc_bid_micros: 2000000, // $2.00
        quality_score: 7,
        final_url: "https://example.com/summer-shoes"
      }
    ],
    total_results: 450
  }
}

GET /keywords/show - Get Single Keyword

Parameters:

• clientID, managerID, adGroupCriterionID, adGroupID (all required)

Response: Single keyword object with full details

GET /keywords/metrics - Keyword Performance Metrics

Parameters: Same as /keywords (date range recommended)

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    keywords: [
      {
        id: "321654987",
        ad_group_name: "Summer Shoes",
        campaign_name: "Summer Sale",
        keyword: {
          text: "summer shoes sale",
          match_type: "BROAD"
        },
        status: "ENABLED",
        metrics: {
          impressions: 8000,
          clicks: 400,
          ctr: 0.05,
          cost_micros: 3000000, // $3.00
          average_cpc: 7500, // $0.0075
          conversions: 8,
          conversion_rate: 0.02,
          cost_per_conversion: 375000, // $0.375
          quality_score: 7,
          historical_quality_score: 8,
          search_impression_share: 0.65
        }
      }
    ]
  }
}

🔧 Match Types

Keyword Match Types:

Broad Match

• Symbol: None
• Example: summer shoes
• Triggers: Variations, synonyms, related searches
• User Search: "buy shoes for summer", "footwear for hot weather"

Phrase Match

• Symbol: "keyword"
• Example: "summer shoes"
• Triggers: Phrase in order, with words before/after
• User Search: "buy summer shoes online", "best summer shoes"

Exact Match

• Symbol: [keyword]
• Example: [summer shoes]
• Triggers: Exact term or close variants
• User Search: "summer shoes", "shoes summer"

Broad Match Modifier (deprecated)

• Symbol: +keyword
• Example: +summer +shoes
• Note: Replaced by phrase match behavior

🔧 Business Logic

GAQL Query Structure:

SELECT
  ad_group_criterion.criterion_id,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.status,
  ad_group_criterion.cpc_bid_micros,
  ad_group_criterion.quality_info.quality_score,
  ad_group.name,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM keyword_view
WHERE ad_group.campaign IN (${campaignIDs})
  AND segments.date BETWEEN '${fromDate}' AND '${endDate}'

Keyword Status:

• ENABLED - Active and eligible to trigger ads
• PAUSED - Paused
• REMOVED - Deleted

Quality Score:

• Scale: 1-10 (10 is best)
• Factors: Expected CTR, ad relevance, landing page experience
• Updates: Calculated regularly by Google

🔧 Quality Score Components

Expected CTR:

• ABOVE_AVERAGE
• AVERAGE
• BELOW_AVERAGE

Ad Relevance:

• ABOVE_AVERAGE
• AVERAGE
• BELOW_AVERAGE

Landing Page Experience:

• ABOVE_AVERAGE
• AVERAGE
• BELOW_AVERAGE

Overall Quality Score: Combination of three factors (1-10)

📊 Keyword Metrics Explained

Impressions: Number of times ad shown for keyword

Clicks: Number of times ad clicked for keyword

CTR: Click-through rate (clicks/impressions)

Cost: Total spend on keyword

Average CPC: Average cost per click

Conversions: Conversion actions completed

Conversion Rate: Conversions/clicks

Quality Score: Google's keyword relevance rating

Search Impression Share: % of eligible impressions received

🎯 Negative Keywords

Purpose: Prevent ads from showing for specific search terms

Types:

• Campaign-level negative keywords
• Ad group-level negative keywords
• Negative keyword lists (shared)

Match Types: Same as regular keywords (broad, phrase, exact)

Example Use Cases:

• Exclude "free" searches if selling products
• Exclude competitor brand names
• Exclude irrelevant search intent

Note: Negative keywords managed through separate API endpoints

⚠️ Important Notes

• 🔐 Hierarchy: Campaign → Ad Group → Keyword
• 💰 CPC Bids: Keyword-level bids override ad group bids
• 📊 Quality Score: Key factor in ad rank and CPC
• 🎯 Match Types: Broader match = more traffic, less control
• 🔗 Negative Keywords: Essential for campaign optimization
• 📝 Keyword Research: Use Google Keyword Planner for ideas
• 🚨 Paused vs Removed: Paused preserves history, removed doesn't

🔗 Related Documentation

• Campaigns
• Ad Groups
• Ads
• Google Ads Keyword Docs
• Match Types Guide