search_geo_locations
Find geographic targeting locations for Meta advertising campaigns by searching countries, regions, cities, and other location types to refine audience targeting.
Instructions
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
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| access_token | No | ||
| location_types | No | ||
| limit | No |
Implementation Reference
- meta_ads_mcp/core/targeting.py:506-538 (handler)The handler function that implements the search_geo_locations tool. It uses the Meta Ads API search endpoint with type='adgeolocation' to find geographic locations matching the query, with optional filters for location types and limit. Returns JSON results.@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)
- meta_ads_mcp/core/__init__.py:14-14 (registration)Import statement in core/__init__.py that registers search_geo_locations by importing from targeting.py, making it available from the core module.from .targeting import search_interests, get_interest_suggestions, estimate_audience_size, search_behaviors, search_demographics, search_geo_locations
- meta_ads_mcp/__init__.py:60-60 (registration)Import and re-export of search_geo_locations from core in the package __init__.py, making it available at the top-level package.search_geo_locations
- Type hints and docstring defining the input schema (query:str required, optional access_token:str, location_types:List[str], limit:int=25) and output as JSON string.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 """