google_ads_search_google_audiences

Instructions

Implementation Reference

• tools/audiences/mcp_tools_audiences.py:757-827 (handler)

  The MCP tool handler that defines the tool, validates inputs, calls the audience manager, formats results, and returns a user-friendly response.

  def google_ads_search_google_audiences(
      customer_id: str,
      search_term: str
  ) -> str:
      """
      Search for Google's predefined audiences (In-Market, Affinity).
  
      Google provides hundreds of pre-built audience segments based on user
      interests and purchase intent. Search to find relevant audiences for
      your business.
  
      Args:
          customer_id: Customer ID (without hyphens)
          search_term: Search term (e.g., "coffee", "fitness", "travel")
  
      Returns:
          List of matching Google audiences
  
      Example:
          google_ads_search_google_audiences(
              customer_id="1234567890",
              search_term="coffee"
          )
  
      Common Categories:
      - In-Market: Users actively researching products (high purchase intent)
      - Affinity: Users with sustained interest in a topic
      - Custom Intent: Create your own based on keywords/URLs
      """
      with performance_logger.track_operation('search_google_audiences', customer_id=customer_id):
          try:
              client = get_auth_manager().get_client()
              audience_manager = AudienceManager(client)
  
              audiences = audience_manager.search_google_audiences(customer_id, search_term)
  
              # Audit log
              audit_logger.log_api_call(
                  customer_id=customer_id,
                  operation="search_google_audiences",
                  resource_type="user_interest",
                  action="read",
                  result="success",
                  details={'search_term': search_term, 'count': len(audiences)}
              )
  
              if not audiences:
                  return f"No Google audiences found matching '{search_term}'. Try different search terms."
  
              # Format response
              output = f"# Google Audiences - Search Results\n\n"
              output += f"**Search Term**: {search_term}\n"
              output += f"**Results Found**: {len(audiences)}\n\n"
  
              for aud in audiences:
                  output += f"## {aud['name']}\n\n"
                  output += f"- **Audience ID**: {aud['user_interest_id']}\n"
                  output += f"- **Category**: {aud['taxonomy_type']}\n"
                  if aud['parent']:
                      output += f"- **Parent Category**: {aud['parent']}\n"
                  output += "\n"
  
              output += f"**Next Steps**:\n"
              output += f"To target these audiences, you'll need to add them to campaigns via the Google Ads UI "
              output += f"or use the audience ID in targeting API calls.\n"
  
              return output
  
          except Exception as e:
              error_msg = ErrorHandler.handle_error(e, context="search_google_audiences")
              return f"❌ Failed to search Google audiences: {error_msg}"

• tools/audiences/mcp_tools_audiences.py:757-760 (schema)

  Input schema: customer_id (str) and search_term (str). Returns a formatted string.

  def google_ads_search_google_audiences(
      customer_id: str,
      search_term: str
  ) -> str:

• google_ads_mcp.py:487-507 (registration)

  Registration entry in _TOOL_MODULES list that maps the audiences module to its register function.

      ("audiences",     "tools.audiences.mcp_tools_audiences",         "register_audience_tools"),
      ("conversions",   "tools.conversions.mcp_tools_conversions",     "register_conversion_tools"),
      ("reporting",     "tools.reporting.mcp_tools_reporting",         "register_reporting_tools"),
      ("insights",      "tools.insights.mcp_tools_insights",           "register_insights_tools"),
      ("batch",         "tools.batch.mcp_tools_batch",                 "register_batch_tools"),
      ("shopping_pmax", "tools.shopping_pmax.mcp_tools_shopping_pmax", "register_shopping_pmax_tools"),
      ("extensions",    "tools.extensions.mcp_tools_extensions",       "register_extension_tools"),
      ("local_app",     "tools.local_app.mcp_tools_local_app",         "register_local_app_tools"),
  ]
  
  
  def _register_all_modular_tools():
      """Import and register every modular tool module."""
      import importlib
  
      registered = 0
      for label, module_path, func_name in _TOOL_MODULES:
          try:
              mod = importlib.import_module(module_path)
              register_fn = getattr(mod, func_name)
              register_fn(mcp)

• google_ads_mcp.py:503-507 (registration)

  Dynamic import and registration of the register_audience_tools function via _register_all_modular_tools()

  for label, module_path, func_name in _TOOL_MODULES:
      try:
          mod = importlib.import_module(module_path)
          register_fn = getattr(mod, func_name)
          register_fn(mcp)

• managers/audience_manager.py:588-627 (handler)

  Core business logic: queries Google Ads API user_interest table with LIKE search, returns matching In-Market/Affinity audiences.

  def search_google_audiences(
      self,
      customer_id: str,
      search_term: str
  ) -> List[Dict[str, Any]]:
      """Search for available Google audiences (In-Market, Affinity).
  
      Args:
          customer_id: Customer ID (without hyphens)
          search_term: Search term to find audiences
  
      Returns:
          List of matching Google audiences
      """
      ga_service = self.client.get_service("GoogleAdsService")
  
      # Search for user interests (In-Market and Affinity audiences)
      query = f"""
          SELECT
              user_interest.user_interest_id,
              user_interest.name,
              user_interest.user_interest_parent,
              user_interest.taxonomy_type
          FROM user_interest
          WHERE user_interest.name LIKE '%{search_term}%'
      """
  
      response = ga_service.search(customer_id=customer_id, query=query)
  
      audiences = []
      for row in response:
          ui = row.user_interest
          audiences.append({
              'user_interest_id': str(ui.user_interest_id),
              'name': ui.name,
              'parent': ui.user_interest_parent,
              'taxonomy_type': ui.taxonomy_type.name
          })
  
      return audiences