meta-ads-mcp-python 1.0.79__py3-none-any.whl

meta_ads_mcp/core/targeting.py

@@ -0,0 +1,542 @@
+"""Targeting search functionality for Meta Ads API."""
+
+import json
+from typing import Optional, List, Dict, Any, Union
+import os
+from .api import meta_api_tool, make_api_request
+from .server import mcp_server
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_interests(query: str, access_token: Optional[str] = None, limit: int = 25) -> str:
+    """
+    Search for interest targeting options by keyword.
+    
+    Args:
+        query: Search term for interests (e.g., "baseball", "cooking", "travel")
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        limit: Maximum number of results to return (default: 25)
+    
+    Returns:
+        JSON string containing interest data with id, name, audience_size, and path fields
+    """
+    if not query:
+        return json.dumps({"error": "No search query provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adinterest",
+        "q": query,
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def get_interest_suggestions(interest_list: List[str], access_token: Optional[str] = None, limit: int = 25) -> str:
+    """
+    Get interest suggestions based on existing interests.
+    
+    Args:
+        interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
+        access_token: Meta API access token (optional - will use cached token if not provided)  
+        limit: Maximum number of suggestions to return (default: 25)
+    
+    Returns:
+        JSON string containing suggested interests with id, name, audience_size, and description fields
+    """
+    if not interest_list:
+        return json.dumps({"error": "No interest list provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adinterestsuggestion", 
+        "interest_list": json.dumps(interest_list),
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def estimate_audience_size(
+    access_token: Optional[str] = None,
+    account_id: Optional[Union[str, int]] = None,
+    targeting: Optional[Dict[str, Any]] = None,
+    optimization_goal: str = "REACH",
+    # Backwards compatibility for simple interest validation
+    interest_list: Optional[List[str]] = None,
+    interest_fbid_list: Optional[List[str]] = None
+) -> str:
+    """
+    Estimate audience size for targeting specifications using Meta's delivery_estimate API.
+    
+    This function provides comprehensive audience estimation for complex targeting combinations
+    including demographics, geography, interests, and behaviors. It also maintains backwards
+    compatibility for simple interest validation.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        account_id: Meta Ads account ID (format: act_XXXXXXXXX) - required for comprehensive estimation
+        targeting: Complete targeting specification including demographics, geography, interests, etc.
+                  Example: {
+                      "age_min": 25,
+                      "age_max": 65,
+                      "geo_locations": {"countries": ["PL"]},
+                      "flexible_spec": [
+                          {"interests": [{"id": "6003371567474"}]},
+                          {"interests": [{"id": "6003462346642"}]}
+                      ]
+                  }
+        optimization_goal: Optimization goal for estimation (default: "REACH"). 
+                          Options: "REACH", "LINK_CLICKS", "IMPRESSIONS", "CONVERSIONS", etc.
+        interest_list: [DEPRECATED - for backwards compatibility] List of interest names to validate
+        interest_fbid_list: [DEPRECATED - for backwards compatibility] List of interest IDs to validate
+    
+    Returns:
+        JSON string with audience estimation results including estimated_audience_size,
+        reach_estimate, and targeting validation
+    """
+    # Coerce numeric IDs to strings
+    if account_id is not None:
+        account_id = str(account_id)
+
+    # Handle backwards compatibility - simple interest validation
+    # Check if we're in backwards compatibility mode (interest params provided OR no comprehensive params)
+    is_backwards_compatible_call = (interest_list or interest_fbid_list) or (not account_id and not targeting)
+    
+    if is_backwards_compatible_call and not targeting:
+        if not interest_list and not interest_fbid_list:
+            return json.dumps({"error": "No interest list or FBID list provided"}, indent=2)
+        
+        endpoint = "search"
+        params = {
+            "type": "adinterestvalid"
+        }
+        
+        if interest_list:
+            params["interest_list"] = json.dumps(interest_list)
+        
+        if interest_fbid_list:
+            params["interest_fbid_list"] = json.dumps(interest_fbid_list)
+        
+        data = await make_api_request(endpoint, access_token, params)
+        
+        return json.dumps(data, indent=2)
+    
+    # Comprehensive audience estimation using delivery_estimate API
+    if not account_id:
+        return json.dumps({
+            "error": "account_id is required for comprehensive audience estimation",
+            "details": "For simple interest validation, use interest_list or interest_fbid_list parameters"
+        }, indent=2)
+    
+    if not targeting:
+        return json.dumps({
+            "error": "targeting specification is required for comprehensive audience estimation",
+            "example": {
+                "age_min": 25,
+                "age_max": 65,
+                "geo_locations": {"countries": ["US"]},
+                "flexible_spec": [
+                    {"interests": [{"id": "6003371567474"}]}
+                ]
+            }
+        }, indent=2)
+    
+    # Preflight validation: require at least one location OR a custom audience
+    def _has_location_or_custom_audience(t: Dict[str, Any]) -> bool:
+        if not isinstance(t, dict):
+            return False
+        geo = t.get("geo_locations") or {}
+        if isinstance(geo, dict):
+            for key in [
+                "countries",
+                "regions",
+                "cities",
+                "zips",
+                "geo_markets",
+                "country_groups"
+            ]:
+                val = geo.get(key)
+                if isinstance(val, list) and len(val) > 0:
+                    return True
+        # Top-level custom audiences
+        ca = t.get("custom_audiences")
+        if isinstance(ca, list) and len(ca) > 0:
+            return True
+        # Custom audiences within flexible_spec
+        flex = t.get("flexible_spec")
+        if isinstance(flex, list):
+            for spec in flex:
+                if isinstance(spec, dict):
+                    ca_spec = spec.get("custom_audiences")
+                    if isinstance(ca_spec, list) and len(ca_spec) > 0:
+                        return True
+        return False
+
+    if not _has_location_or_custom_audience(targeting):
+        return json.dumps({
+            "error": "Missing target audience location",
+            "details": "Select at least one location in targeting.geo_locations or include a custom audience.",
+            "action_required": "Add geo_locations with countries/regions/cities/zips or include custom_audiences.",
+            "example": {
+                "geo_locations": {"countries": ["US"]},
+                "age_min": 25,
+                "age_max": 65
+            }
+        }, indent=2)
+    
+    # Build reach estimate request (using correct Meta API endpoint)
+    endpoint = f"{account_id}/reachestimate"
+    params = {
+        "targeting_spec": targeting
+    }
+    
+    # Note: reachestimate endpoint doesn't support optimization_goal or objective parameters
+    
+    try:
+        data = await make_api_request(endpoint, access_token, params, method="GET")
+        
+        # Surface Graph API errors directly for better diagnostics.
+        # If reachestimate fails, optionally attempt a fallback using delivery_estimate.
+        if isinstance(data, dict) and "error" in data:
+            # Special handling for Missing Target Audience Location error (subcode 1885364)
+            try:
+                err_wrapper = data.get("error", {})
+                details_obj = err_wrapper.get("details", {})
+                raw_err = details_obj.get("error", {}) if isinstance(details_obj, dict) else {}
+                if (
+                    isinstance(raw_err, dict) and (
+                        raw_err.get("error_subcode") == 1885364 or
+                        raw_err.get("error_user_title") == "Missing Target Audience Location"
+                    )
+                ):
+                    return json.dumps({
+                        "error": "Missing target audience location",
+                        "details": raw_err.get("error_user_msg") or "Select at least one location, or choose a custom audience.",
+                        "endpoint_used": f"{account_id}/reachestimate",
+                        "action_required": "Add geo_locations with at least one of countries/regions/cities/zips or include custom_audiences.",
+                        "blame_field_specs": raw_err.get("error_data", {}).get("blame_field_specs") if isinstance(raw_err.get("error_data"), dict) else None
+                    }, indent=2)
+            except Exception:
+                pass
+            # Allow disabling fallback via environment variable
+            # Default: fallback disabled unless explicitly enabled by setting DISABLE flag to "0"
+            disable_fallback = os.environ.get("META_MCP_DISABLE_DELIVERY_FALLBACK", "1") == "1"
+            if disable_fallback:
+                return json.dumps({
+                    "error": "Graph API returned an error for reachestimate",
+                    "details": data.get("error"),
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "request_params": {
+                        "has_targeting_spec": bool(targeting),
+                    },
+                    "note": "delivery_estimate fallback disabled via META_MCP_DISABLE_DELIVERY_FALLBACK"
+                }, indent=2)
+
+            # Try fallback to delivery_estimate endpoint
+            try:
+                fallback_endpoint = f"{account_id}/delivery_estimate"
+                fallback_params = {
+                    "targeting_spec": json.dumps(targeting),
+                    # Some API versions accept optimization_goal here
+                    "optimization_goal": optimization_goal
+                }
+                fallback_data = await make_api_request(fallback_endpoint, access_token, fallback_params, method="GET")
+                
+                # If fallback returns usable data, format similarly
+                if isinstance(fallback_data, dict) and "data" in fallback_data and len(fallback_data["data"]) > 0:
+                    estimate_data = fallback_data["data"][0]
+                    formatted_response = {
+                        "success": True,
+                        "account_id": account_id,
+                        "targeting": targeting,
+                        "optimization_goal": optimization_goal,
+                        "estimated_audience_size": estimate_data.get("estimate_mau", 0),
+                        "estimate_details": {
+                            "monthly_active_users": estimate_data.get("estimate_mau", 0),
+                            "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
+                            "bid_estimate": estimate_data.get("bid_estimates", {}),
+                            "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
+                        },
+                        "raw_response": fallback_data,
+                        "fallback_endpoint_used": "delivery_estimate"
+                    }
+                    return json.dumps(formatted_response, indent=2)
+                
+                # Fallback returned but not in expected format
+                return json.dumps({
+                    "error": "Graph API returned an error for reachestimate; delivery_estimate fallback did not return usable data",
+                    "reachestimate_error": data.get("error"),
+                    "fallback_endpoint_used": "delivery_estimate",
+                    "fallback_raw_response": fallback_data,
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "request_params": {
+                        "has_targeting_spec": bool(targeting)
+                    }
+                }, indent=2)
+            except Exception as _fallback_exc:
+                return json.dumps({
+                    "error": "Graph API returned an error for reachestimate; delivery_estimate fallback also failed",
+                    "reachestimate_error": data.get("error"),
+                    "fallback_endpoint_used": "delivery_estimate",
+                    "fallback_exception": str(_fallback_exc),
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "request_params": {
+                        "has_targeting_spec": bool(targeting)
+                    }
+                }, indent=2)
+
+        # Format the response for easier consumption
+        if "data" in data:
+            response_data = data["data"]
+            # Case 1: delivery_estimate-like list structure
+            if isinstance(response_data, list) and len(response_data) > 0:
+                estimate_data = response_data[0]
+                formatted_response = {
+                    "success": True,
+                    "account_id": account_id,
+                    "targeting": targeting,
+                    "optimization_goal": optimization_goal,
+                    "estimated_audience_size": estimate_data.get("estimate_mau", 0),
+                    "estimate_details": {
+                        "monthly_active_users": estimate_data.get("estimate_mau", 0),
+                        "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
+                        "bid_estimate": estimate_data.get("bid_estimates", {}),
+                        "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
+                    },
+                    "raw_response": data
+                }
+                return json.dumps(formatted_response, indent=2)
+            # Case 1b: explicit handling for empty list responses
+            if isinstance(response_data, list) and len(response_data) == 0:
+                return json.dumps({
+                    "error": "No estimation data returned from Meta API",
+                    "raw_response": data,
+                    "debug_info": {
+                        "response_keys": list(data.keys()) if isinstance(data, dict) else "not_a_dict",
+                        "response_type": str(type(data)),
+                        "endpoint_used": f"{account_id}/reachestimate"
+                    }
+                }, indent=2)
+            # Case 2: reachestimate dict structure with bounds
+            if isinstance(response_data, dict):
+                lower = response_data.get("users_lower_bound", response_data.get("estimate_mau_lower_bound"))
+                upper = response_data.get("users_upper_bound", response_data.get("estimate_mau_upper_bound"))
+                estimate_ready = response_data.get("estimate_ready")
+                midpoint = None
+                try:
+                    if isinstance(lower, (int, float)) and isinstance(upper, (int, float)):
+                        midpoint = int((lower + upper) / 2)
+                except Exception:
+                    midpoint = None
+                formatted_response = {
+                    "success": True,
+                    "account_id": account_id,
+                    "targeting": targeting,
+                    "optimization_goal": optimization_goal,
+                    "estimated_audience_size": midpoint if midpoint is not None else 0,
+                    "estimate_details": {
+                        "users_lower_bound": lower,
+                        "users_upper_bound": upper,
+                        "estimate_ready": estimate_ready
+                    },
+                    "raw_response": data
+                }
+                return json.dumps(formatted_response, indent=2)
+        else:
+            return json.dumps({
+                "error": "No estimation data returned from Meta API",
+                "raw_response": data,
+                "debug_info": {
+                    "response_keys": list(data.keys()) if isinstance(data, dict) else "not_a_dict",
+                    "response_type": str(type(data)),
+                    "endpoint_used": f"{account_id}/reachestimate"
+                }
+            }, indent=2)
+    
+    except Exception as e:
+        # Try fallback to delivery_estimate first when an exception occurs (unless disabled)
+        # Default: fallback disabled unless explicitly enabled by setting DISABLE flag to "0"
+        disable_fallback = os.environ.get("META_MCP_DISABLE_DELIVERY_FALLBACK", "1") == "1"
+        if not disable_fallback:
+            try:
+                fallback_endpoint = f"{account_id}/delivery_estimate"
+                fallback_params = {
+                "targeting_spec": json.dumps(targeting) if isinstance(targeting, dict) else targeting,
+                "optimization_goal": optimization_goal
+            }
+                fallback_data = await make_api_request(fallback_endpoint, access_token, fallback_params, method="GET")
+            
+                if isinstance(fallback_data, dict) and "data" in fallback_data and len(fallback_data["data"]) > 0:
+                    estimate_data = fallback_data["data"][0]
+                    formatted_response = {
+                        "success": True,
+                        "account_id": account_id,
+                        "targeting": targeting,
+                        "optimization_goal": optimization_goal,
+                        "estimated_audience_size": estimate_data.get("estimate_mau", 0),
+                        "estimate_details": {
+                            "monthly_active_users": estimate_data.get("estimate_mau", 0),
+                            "daily_outcomes_curve": estimate_data.get("estimate_dau", []),
+                            "bid_estimate": estimate_data.get("bid_estimates", {}),
+                            "unsupported_targeting": estimate_data.get("unsupported_targeting", [])
+                        },
+                        "raw_response": fallback_data,
+                        "fallback_endpoint_used": "delivery_estimate"
+                    }
+                    return json.dumps(formatted_response, indent=2)
+            except Exception as _fallback_exc:
+                # If fallback also fails, proceed to detailed error handling below
+                pass
+
+        # Check if this is the specific Business Manager system user permission error
+        error_str = str(e)
+        if "100" in error_str and "33" in error_str:
+            # Try to provide fallback estimation using individual interests if available
+            interests_found = []
+            if targeting and "interests" in targeting:
+                interests_found.extend([interest.get("id") for interest in targeting["interests"] if interest.get("id")])
+            elif targeting and "flexible_spec" in targeting:
+                for spec in targeting["flexible_spec"]:
+                    if "interests" in spec:
+                        interests_found.extend([interest.get("id") for interest in spec["interests"] if interest.get("id")])
+            
+            if interests_found:
+                # Attempt to get individual interest data as fallback
+                try:
+                    fallback_result = await estimate_audience_size(
+                        access_token=access_token,
+                        interest_fbid_list=interests_found
+                    )
+                    fallback_data = json.loads(fallback_result)
+                    
+                    return json.dumps({
+                        "comprehensive_targeting_failed": True,
+                        "error_code": "100-33",
+                        "fallback_used": True,
+                        "details": {
+                            "issue": "reachestimate endpoint returned error - possibly due to targeting parameters or account limitations",
+                            "solution": "Individual interest validation used as fallback - comprehensive targeting may have specific requirements",
+                            "endpoint_used": f"{account_id}/reachestimate"
+                        },
+                        "individual_interest_data": fallback_data,
+                        "note": "Individual interest audience sizes provided as fallback. Comprehensive targeting via reachestimate endpoint failed."
+                    }, indent=2)
+                except:
+                    pass
+            
+            return json.dumps({
+                "error": "reachestimate endpoint returned error (previously was incorrectly using delivery_estimate)",
+                "error_code": "100-33", 
+                "details": {
+                    "issue": "The endpoint returned an error, possibly due to targeting parameters or account limitations",
+                    "endpoint_used": f"{account_id}/reachestimate",
+                    "previous_issue": "Code was previously using non-existent delivery_estimate endpoint - now fixed",
+                    "available_alternative": "Use interest_list or interest_fbid_list parameters for individual interest validation"
+                },
+                "raw_error": error_str
+            }, indent=2)
+        else:
+            return json.dumps({
+                "error": f"Failed to get audience estimation from reachestimate endpoint: {str(e)}",
+                "details": "Check targeting parameters and account permissions",
+                "error_type": "general_api_error",
+                "endpoint_used": f"{account_id}/reachestimate"
+            }, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_behaviors(access_token: Optional[str] = None, limit: int = 50) -> str:
+    """
+    Get all available behavior targeting options.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        limit: Maximum number of results to return (default: 50)
+    
+    Returns:
+        JSON string containing behavior targeting options with id, name, audience_size bounds, path, and description
+    """
+    endpoint = "search"
+    params = {
+        "type": "adTargetingCategory",
+        "class": "behaviors",
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_demographics(access_token: Optional[str] = None, demographic_class: str = "demographics", limit: int = 50) -> str:
+    """
+    Get demographic targeting options.
+    
+    Args:
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        demographic_class: Type of demographics to retrieve. Options: 'demographics', 'life_events', 
+                          'industries', 'income', 'family_statuses', 'user_device', 'user_os' (default: 'demographics')
+        limit: Maximum number of results to return (default: 50)
+    
+    Returns:
+        JSON string containing demographic targeting options with id, name, audience_size bounds, path, and description
+    """
+    endpoint = "search"
+    params = {
+        "type": "adTargetingCategory",
+        "class": demographic_class,
+        "limit": limit
+    }
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)
+
+
+@mcp_server.tool()
+@meta_api_tool
+async def search_geo_locations(query: str, access_token: Optional[str] = None, 
+                             location_types: Optional[List[str]] = None, limit: int = 25) -> str:
+    """
+    Search for geographic targeting locations.
+    
+    Args:
+        query: Search term for locations (e.g., "New York", "California", "Japan")
+        access_token: Meta API access token (optional - will use cached token if not provided)
+        location_types: Types of locations to search. Options: ['country', 'region', 'city', 'zip', 
+                       'geo_market', 'electoral_district']. If not specified, searches all types.
+        limit: Maximum number of results to return (default: 25)
+    
+    Returns:
+        JSON string containing location data with key, name, type, and geographic hierarchy information
+    """
+    if not query:
+        return json.dumps({"error": "No search query provided"}, indent=2)
+    
+    endpoint = "search"
+    params = {
+        "type": "adgeolocation",
+        "q": query,
+        "limit": limit
+    }
+    
+    if location_types:
+        params["location_types"] = json.dumps(location_types)
+    
+    data = await make_api_request(endpoint, access_token, params)
+    
+    return json.dumps(data, indent=2)