Comscore

Searches for media entities (sites/apps) by name. Intended for questions like "what sites match X" or "find the ID for Y". get_metric, get_trend, get_demographics, get_audience_overlap, and get_cross_visiting resolve media internally and do not require a prior find_media call. This is a prefix search — query="Nexstar" returns all Nexstar entities in one call. Args: query: Site, app, or brand as the user names it (e.g. "HBO", "cnn.com") — pass it verbatim, don't convert a brand to a domain. Use the shortest parent name to get the full portfolio. geo: Geographic market, default "US". product: Product slug for context, default "mmx". report: Report slug for context, default "keymeasures". time_period: Numeric period code. Defaults to last published month. exact_match: Require exact name match, default False.

Audience overlap (duplication) across 2–10 sites/apps — the shared audience and what fraction of each entity's audience also visits the others. For MMX, platform="multiplatform" (the default) returns Total Digital Population, Desktop, AND Mobile breakdowns together under each entity's "by_platform" key — a single call covers all three; separate desktop and mobile calls return data already present in the multiplatform response. Reports a per-entity value for every requested metric plus the duplicated audience ("2 or More Sites" and "All Sites") and the combined unduplicated total. Supports an audience filter (age/gender/HH-size etc.) and US local markets (CS Markets). Args: media: 2–10 entities as the user names them (e.g. ["HBO", "ESPN", "cnn.com"]) — pass each verbatim, don't convert a brand to a domain. metrics: Metrics to report, e.g. ["unique visitors", "reach", "minutes", "average minutes per visitor"]. Defaults to unique visitors + % reach. (mmx only; video/mobile products report unique visitors.) audience: Optional audience filter. Pass a single string ("women 25-54", "adults 18+", "HH Size: 1") for a standard filter, OR a list of strings to combine multiple segments as an Advanced Audience (e.g. ["HH Size: 1", "HH Size: 2", "HH Size: 3"]). Multiple segments are OR-combined into one request (targetType=1). Omit for total. time: "last_month" (default), "YYYY-MM", or raw period integer. geo: "US" (default), a country, or a US local market / CS Market (e.g. "Boston, MA"). CS Markets run on the MMX Desktop data source only (no Mobile/TDP breakdown), and are available for the mmx product only. product: "mmx" (default), "video" (VMX), "mobile". platform: "multiplatform" (default) — use this for all MMX requests. Returns TDP + Desktop + Mobile in one call. "desktop" or "mobile" only when the user explicitly requests a single platform view with no breakdown needed. Ignored for video/mobile products.

Other sites that a site's audience also visits (affinity / cross-visiting). Returns, per co-visited site/category, the shared audience and the requested cross-visiting metrics. Args: media: Base site/app/brand as the user names it — pass it verbatim. For multiple base entities pass a list or a semicolon-joined string ("PayPal;CNN.COM"). time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US" (e.g. "Brazil" for non-US). product: "mmx" (default), "video" (VMX), "mobile". platform: "multiplatform" (default), "desktop", "mobile". Ignored for video/mobile. limit: Co-visited sites to return, default 100. target_category: Target entity category whose members become the rows — an industry ("Automotive", "News") or a rollup ("Top 100 Properties", default). Mutually exclusive with target_entities. target_entities: Specific target entities to use as rows (Digital Entities mode), e.g. ["CNN Brasil", "CNNBRASIL.COM.BR"]. List or semicolon-joined string. When set, only these entities are returned (overrides target_category). metrics: Cross-visiting metrics, e.g. ["Shared Audience (000)", "% Vertical", "% Horizontal", "Index"]. List or semicolon-joined string. Defaults to all four. audience: Audience filter. Single string ("Total Audience", "Males 21+") for a standard target, or a list to combine segments as an Advanced Audience (targetType=1), e.g. ["Females 45+", "Females 35-44"]. Omit for Total Audience. domains_only: When True, expand categories to individual domains (leaf entities) rather than brand/property rollups. Maps to the report's "domains only" option.

Full demographic breakdown for a site. Use for Demographic Profile, Demographic Breakouts, and any widget asking for age/gender/region/income breakdown of an entity's audience. Use instead of calling get_metric repeatedly with different targets. Args: media: Site, app, or brand as the user names it — pass it verbatim, don't convert a brand to a domain. For multiple entities pass comma-separated names, e.g. "Yahoo,Yahoo Sports". time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". product: "mmx" (default), "video" (VMX), "mobile". platform: "multiplatform" (default), "desktop", "mobile". Ignored for video/mobile. audience: Comma-separated demographic dimensions to break down by (e.g. "Children,HH Size", "Region,Language", "Persons"). Default: age/gender breakdown. Valid segments: standard age/gender targets, plus "Children", "HH Size", "HHI" (household income), "Race", "Region", "Language". Prefix with "advanced," for a filtered single segment (e.g. "advanced,Children: Yes"). metrics: List of metrics to return alongside UV (e.g. ["% Reach", "% Composition", "Total Visits", "Total Views"]). Default: unique visitors only. For multiplatform, % Reach breakdown by Desktop/Mobile is always included. audience_universe: Audience universe for multiplatform MMX, same values as get_metric (e.g. "Desktop 2+ and Total Mobile 18+", "Desktop 2+ and Total Mobile 13+"). Defaults to "Desktop 2+ and Total Mobile 18+" (universeTypeId 4), which the demographicprofile report requires to return data for multiplatform/mobile.

Entity Status widget — shows measurement coverage for a site/publisher across platforms (Desktop, Smartphone iOS/Android, CTV) and content types (Display, Video). Use for the Entity Status widget or when the user asks about measurement/tagging status. Args: media: Site, category, or brand (e.g. "CNN.COM", "Social", "ESPN.com Sites"). time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". entity_type: "Digital Entities" (default) for a specific site/brand, or "Digital Categories" for a category (e.g. "Social", "News") — a category returns the measurement status of every property within it.

Single-month metric for a site or publisher. For multiple months use get_trend; for full demographic breakdown use get_demographics. Never call find_media first. - Multiple months ("last 6 months", date range) → use get_trend - Full age/gender breakdown → use get_demographics; use target= here only for a single segment - Ranked list of sites in a category (Media Ranker, Industry Ranker) → use get_top_entities, NOT this tool - EXCEPTION: if specific named entities are given (e.g. "OUTKICK.COM;PayPal"), use get_metric for each entity individually — do NOT use get_top_entities when specific entities are listed - Lifestyle/behavioral/psychographic audience (e.g. "married", "EV buyer", "gamer") → use get_plan_metrix instead; target= only accepts standard age/gender demo labels - Sub-properties or channels (e.g. "CNN by section") → expand_all_media=True - Company properties (e.g. "Microsoft properties", "Google sites") → media="Microsoft", expand_all_media=True. Comscore has a parent/child media tree; the publisher is the parent and its sites/apps are children. Never ask the user to list domains. Args: media: Site, app, or brand as the user names it (e.g. "HBO", "cnn.com") — pass it verbatim, including any qualifier in parentheses (e.g. "ESPN (Mobile App)", "CNN (TV App)"). Never strip qualifiers or convert a brand to a domain. metric: "unique visitors", "reach", "minutes", "pages", "page views (mm)", "visits", "frequency", "viewers", "video views", "composition index", "% composition", "composition index videos", "composition index minutes", "% composition minutes", "avg daily visitors", "desktop-only uv", "mobile-only uv" (multiplatform mmx only — exclusive audiences), (and aliases like "people", "UV", "time spent"). "Composition index" / "% composition" express how concentrated the audience is vs. the target's universe — they require target= to be set to be meaningful (mmx only). time: "last_month", "YYYY-MM", or raw period integer. geo: Geographic market, default "US". product: "mmx" (default, web+app), "video" (VMX), "mobile" (Mobile Metrix). platform: For mmx: "desktop" (default), "multiplatform" (desktop+mobile), "mobile". For video: "multiplatform" (default, = Desktop+Mobile+CTV), "desktop", "mobile", "ctv". limit: Max rows, default 10. target: Demographic segment — "gen z", "women", "18-24", "men 25-34", etc. For combined/Advanced Audience (multiple segments OR'd), prefix with "advanced," e.g. "advanced,Males: 65+,Males: 55-64,Females: 65+". These are OR-combined (targetType=1) and returned as a single aggregate value. expand_all_media: True to return sub-property breakdown with hierarchy (depth, parent_id). beta_data: True to use Comscore beta/preview data instead of standard production data (the UI "beta data" toggle). Default False (standard). mmx only. percent_change: True to also fetch the prior month and report the change vs. that period (adds prev_value/prev_value_human/percent_change to output). audience_universe: Audience universe for multiplatform MMX reports. Only applies when platform="multiplatform". Valid values: "Desktop 2+ and Total Mobile 18+" (id=4, default for most markets), "Desktop 2+ and Total Mobile 13+" (id=6), "Desktop 6+ and Total Mobile 18+" (id=4, some geos), "Default" or omit for no universe filter. include_total_internet: True to also fetch the Total Internet baseline for the same geo/time/target and include it alongside the entity result. Mirrors the UI "Include Total Internet" toggle. A report submission error from this tool indicates an invalid parameter combination and should be surfaced to the user.

Plan Metrix metrics (views, visitors, reach, etc.) for a custom audience segment. Use this tool whenever the audience is anything other than a plain age/gender demo — including: household size, income, education, purchase intent, lifestyle, psychographics, or ANY combination of multiple segments (e.g. Female AND household size 2 or 3). get_metric only accepts a single age/gender target; all other audience definitions require this tool. search_plan_metrix_audience returns the numeric segment IDs this tool requires. For demographic breakdown queries (e.g. "show results by Hispanic sub-segment"), media="total internet" is appropriate — the audience segments are the rows, not a media filter. Audience expressions combine all required segments: use ^ (AND) / | (OR) to compose a single expression (e.g. "A^B|A^C"). Each call covers one expression; one combined call is more efficient than multiple calls with individual segment IDs. CROSSTAB MODE: When the user asks for a matrix of row segments × column segments (e.g. "show Hispanic sub-segments as rows and music purchase categories as columns"), pass: - audience_rows: the row segment expression (e.g. "6607|4827|5965") - audience: the column segment expression (e.g. "859216|859640|859641") - metric: "target audience (000)" and/or "% vertical" — both are returned natively in one call. This uses a single API call instead of N×M separate calls. Always prefer this over looping. Args: media: "total internet" for universe figures, a PMX category name (e.g. "Entertainment", "Automotive", "News"), or a specific domain/brand name (e.g. "netflix.com"). Pass the name directly — do NOT pass a numeric ID here. audience: Boolean expression of numeric segment IDs (column segments in crosstab mode). Operators: ^ (AND), | (OR), ! (NOT). NO parentheses — API rejects them. Use distributive law: (A|B)^C → A^C|B^C E.g. "583658", "583658^5425", "583658|583655", "583658^!12417" metric: "unique visitors" (default), "reach", "total minutes", "total views", "total pages", "total visits", "avg minutes", "avg visits", "composition index", "composition %", "% vertical" (crosstab only). Note: "total views" and "total pages" both map to the same Plan Metrix measure — the Core UI labels it "Total Views MM". time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". platform: "desktop+mobile" (default), "desktop", "mobile". "desktop+mobile" returns the combined/total across platforms in a single call with deduplication handled internally. Two separate calls (desktop + mobile) do not produce an accurate combined figure. audience_rows: Row segment expression for crosstab mode. When set, `audience` becomes the column expression and a single consumertargetprofilev2 call returns the full matrix with Target Audience (000) and % Vertical for every row × column cell. Use the same boolean expression syntax as `audience`.

Ranked list of top entities within a category. USE THIS TOOL for Media Ranker, Media Industry Ranker, and any widget that shows a ranked list of sites/publishers within an industry or category. When the user specifies an entity (e.g. "CNN.COM") as the context for a ranker, find that entity's industry category and pass it as `category` — do NOT call get_metric for the entity; that returns only a single value, not a ranked list. Common entity → category mappings (use search_category if unsure): CNN.COM, BBC → "News" or "General News" Spotify, Apple Music → "Entertainment - Music" or "Entertainment" ESPN, BBC Sport → "Sports" YouTube, Netflix → "Streaming Video" SHOPIFY.COM → "Retail" Adobe Sites → "Technology" PSG.FR, sports teams → "Sports" NPR.ORG → "News" OUTKICK.COM → "Sports" or "News" Lifestyles / BDG Lifestyles / lifestyle brands → "Lifestyles" Automotive brands → "Automotive" Health/medical → "Health" Travel brands → "Travel" For Mobile Metrix ranker (product="mobile"), pass the same category name — it maps to the correct mobile-specific mediaSet automatically. product='video' (VMX) IS supported — use it for video publisher / streaming queries. product='mobile' (Mobile Metrix) IS supported — use it for mobile audience queries. product='mmx' is the default for general web audience queries. Product routing: - "top video publishers", "streaming", "video views", "viewers" → product='video', metric='video views' - "top mobile apps/sites", "mobile audience" → product='mobile' - everything else → product='mmx' Supported metrics by product (use these alias names): mmx (multiplatform): 'unique visitors', 'reach', 'minutes', 'pages', 'visits', 'video views', 'frequency', 'median age', 'mean age' mmx (desktop only): all above + 'composition index' video (VMX): 'video views', 'viewers' (=unique viewers/reach 000), 'minutes', 'reach', 'frequency', 'videos per viewer' mobile: 'unique visitors', 'reach', 'minutes', 'pages', 'visits', 'frequency', 'median age', 'mean age', 'median income' Args: category: "top 100" for general queries; verticals: "news", "sports", "automotive", "health", "travel", "finance", "technology", "retail", "social media", "streaming video", etc. Call search_category if unsure. For Media Industry Ranker: pass the entity's industry category, not the entity itself. metric: Metric to rank by, default "unique visitors". For multiplatform metrics specify the platform suffix, e.g. "unique visitors, Desktop and Mobile" or "% Reach, Desktop". time: "last_month" (default), "YYYY-MM", or raw period integer. geo: Geographic market, default "US". product: "mmx" (default), "video" (VMX), or "mobile" (Mobile Metrix). platform: "multiplatform" (default), "desktop", "mobile". For video: also "ctv". limit: Top N to return (default 100, max 100).

Multi-month time series for a site metric. Use for trends, "last N months", or any date range. Never call find_media first. Args: media: Site, app, or brand as the user names it — pass it verbatim, including any qualifier in parentheses (e.g. "ESPN (Mobile App)", "CNN (TV App)"). Never strip qualifiers or convert a brand to a domain. metric: Same vocabulary as get_metric. time_range: "last_3_months" (default), "last_6_months", "last_12_months", or "YYYY-MM:YYYY-MM". geo: Geographic market, default "US". product: "mmx" (default), "video" (VMX), "mobile". platform: For mmx: "desktop" (default), "multiplatform" (desktop+mobile), "mobile". For video: "multiplatform" (default, = Desktop+Mobile+CTV), "desktop", "mobile", "ctv". limit: Max rows, default 0 (all months). target: Single demographic segment — same vocabulary as get_metric. audience_universe: Audience universe for multiplatform MMX — same values as get_metric. include_total_internet: True to also return a Total Internet baseline series. expand_all_media: True to return sub-property trend breakdown (e.g. CNN sections over time). A report submission error from this tool indicates an invalid parameter combination and should be surfaced to the user.

List all metrics available for a given product and platform by querying the API live. Returns the authoritative metric list for questions like "what metrics are available", "what can I measure", or "what views/reach/minutes metrics exist" for a given data source. Args: product: "mmx" (default, desktop+mobile web), "video" (VMX), "mobile" (Mobile Metrix). platform: "multiplatform" (default), "desktop", "mobile". For mmx: "multiplatform" = dataSource=25, "desktop" = dataSource=1. geo: Geographic market, default "US".