Comscore

Ranked list of top entities within a category. Covers Media Ranker, Media Industry Ranker, and any widget that shows a ranked list of sites/publishers within an industry or category. When an entity (e.g. "CNN.COM") is the context for a ranker, that entity's industry category is passed as `category` and the ranked list is returned (a single-entity value is the domain of get_metric). Common entity → category mappings (search_category resolves an unknown category): 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. search_category resolves an unknown category. Subcategories are accepted by their Comscore name, e.g. "Lifestyles - Food", "Entertainment - Music", "e-mail". For Media Industry Ranker: this is the entity's industry category, not the entity itself. Also accepts the exact name of the user's own private MMX Saved Group (product="mmx" only) — a custom list of entities they built and saved in the Comscore web UI. Tried automatically as a fallback when the name doesn't match a known category; ranks that group's own member entities instead of an industry vertical. 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). audience: Optional demographic audience to rank by (product="mmx" only), e.g. "Hispanic", "women 25-54", "adults 18+". Ranks the category's entities by their audience within that demographic. Omit for total audience. A Hispanic audience goes here, not in geo.

get_top_entities

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. The result also carries logged_in_as, the Comscore username the session runs as, so call this for "who am I logged in as" too. Args: product: "mmx" (default, desktop+mobile web), "video" (VMX), "mobile" (Mobile Metrix). platform: "multiplatform" (default), "desktop", "mobile"; also "ctv" for video. For video it lists that platform's measures for the geo, or says the platform is not measured there (CTV is measured in only a few countries). For mmx: "multiplatform" = dataSource=25, "desktop" = dataSource=1. geo: "US" (default), a country, or a US local market / CS Market (e.g. "New York"). CS Markets list the MMX Desktop measures, the only ones reported there.

list_metrics

Lists predefined media indices (e.g. "U.S. Media 100 Index") that can be passed as `category_set` to social_power_rankings, instead of entity_ids. Use the returned `name` values verbatim.

social_list_category_sets

Lists the metric names accepted by social_metrics and social_power_rankings. Use the returned `name` values verbatim. `trendable` marks metrics that can be requested as a time series (granularity day/week/month) in social_metrics. `private` marks metrics from the page's own insights: they have values only for properties authed with the user's Comscore account, and come back as "private" for every other property. Prefer the public metrics unless the user asks for insights data. Args: services: Optional filter — one or more of facebook, instagram, twitter, youtube, tiktok. Omit for all.

social_list_metrics

Retrieves the next page of results for a TV tool response that included a next_page_token. Each page's response carries its own next_page_token; a null token indicates the last page. Args: next_page_token: The token from the previous response's next_page_token field.

tv_retrieve_next_page

Find available category names for get_top_entities. Searches Comscore's full US Ranked Categories list, including subcategories such as "Lifestyles - Food" or "e-mail". Args: query: Partial name to search (case-insensitive), e.g. "auto", "health".

search_category

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. To explain what an entity is made of (its named sites and sections), call get_metric with expand_all_media=True. Args: query: Site, app, or brand as the user names it (e.g. "HBO", "cnn.com"), passed verbatim; a brand is not equivalent to its domain. The shortest parent name returns the full portfolio. geo: "US" (default), a country, or a US local market / CS Market (e.g. "New York"). A CS Market search lists the MMX Desktop entities, the only ones reported there. 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.

find_media

Search the audience segment catalog (~5700 segments) across every data layer get_plan_metrix can target. Returns the numeric segment IDs that get_plan_metrix accepts as input. The catalog spans several data layers, and each match says which layer it came from: - "Plan Metrix" — the survey itself (claimed purchases, ownership, activities, attitudes). - "IAB Digital Interests 2.0" — behavioural interest signals from measured browsing, organised on the IAB content taxonomy (e.g. Business and Finance > Venture Capital, Movies > Horror Movies). - "Demos" / "Demos - Hispanic" — age, gender, income, household size, race breakouts. Segments from different layers combine freely in one get_plan_metrix `audience` expression, so a definition can mix a survey answer with an IAB interest signal. Which layer a segment belongs to changes what it measures — an IAB interest is browsing behaviour, a Plan Metrix segment is a survey response — so state the layer alongside any number derived from it. Choosing segments — ask before pulling data: - If exactly one match fits the audience the user described, use it directly. - If two or more matches each fit it (e.g. "VP/C-suite" matches both Work Demos > Title > Executive (C-Level) and Management (VP, Director, Manager)), do NOT call get_plan_metrix yet. List those matches by name and ask the user which to use, offering their OR combination as an option, then pull the data. `answer_groups` lists matches that are answers to the same catalog question, with the OR expression ready to offer, plus `other_answers`: the rest of that question's answers in the catalog that the query did not match. When the user asks for every option of a kind (e.g. all California vacation destinations), pick the fitting ones from `other_answers` too — the matches alone are only the ones the wording hit. - Each Plan Metrix survey match has a `kind`: "opinion" (a stated preference, e.g. "I prefer foreign trips") or "behavior" (what people do, buy or own, e.g. international trips taken). The two answer different briefs. When the fitting matches include both kinds, do not choose between them: ask the user whether they want the preference, the action or both before pulling data. When they are all one kind, search once more for the other kind before choosing. Writing the options — the user must be able to check each one against an audience definition they already have, so: - Name every segment an option contains by its signal name, as it reads here. No segment IDs and no ^ | ! operators — say AND, OR, EXCLUDING. Never summarise a set as "any resolved X" or "the segments that resolved cleanly"; an option that ORs a long answer group lists every answer in it. In a multiple-choice prompt with short labels, list them in each option's description. - Build options only from segments a search returned. Never ask the user for segment names or IDs — search again with other wording instead. - If part of the request has no matching signal (e.g. "heavy": Plan Metrix records whether someone used a service, not how much), say so and name the nearest signals. - If the request does not say how its parts combine, spell out the grouping in words and ask which one the user means — it changes the numbers. Args: query: Natural language audience description, e.g. "podcast listener", "venture capital", "angel investment", "horror movies", "TikTok user". layer: Optional data-layer filter. Accepts "iab" (IAB Digital Interests 2.0), "plan metrix" (the survey), or "demos". Omit to search every layer, which is usually right — the best segment for a query is often in a layer the caller did not think to ask for. limit: Max matches to return, default 10.

search_plan_metrix_audience

Searches this account's Social property list by name (brands/accounts). Use it to find the `entity_id` for a property, which every other social tool needs (or pass the name directly via the `names` param on those tools). The search is scoped to the properties on the account's own list, which for many accounts is a short one — so an empty result means only that nothing on this list is named like the query. It does not mean the brand is unmeasured, and it does not mean the account may not report on it: an `entity_id` obtained any other way still works, because properties are not per-user entitlements. Args: query: Free-text name to search for (e.g. "MrBeast"). limit: Max properties to return (default 20).

social_search_properties

Discover and resolve TV demographic/segment IDs — including Political, Automotive, Plan Metrix, and other custom audience segments. Common labels (A18-49, A25-54, M18-49, W25-54, HH, "household", etc.) do not need this tool — the high-level tools (tv_viewership_by_program, tv_viewership_by_time, tv_demographics) accept them directly via the `demo`/`demo_groups` parameter and resolve standard demos internally (e.g. demo="HH"). This tool covers everything else, via one of three modes: 1. LIST CATALOGS (no arguments): returns the segment "owner" families available — e.g. "Comscore Political Segments", "Comscore Automotive - Local", "Comscore Plan Metrix". Start here when a user mentions Political, Automotive, or Plan Metrix segments and you don't yet know what exists. 2. LIST GROUPS (owner=...): returns the demo groups under an owner, each with its demo_group_no, demo_group_name, and whether it is available locally/nationally. E.g. owner="Comscore Political Segments" returns per-state groups like "Political In-State NE v3 - 08.27.2018 to Ongoing" (group 8541). Groups flagged local can be broken out per market; national-only groups cannot. demo_local=true means the group is usable via tv_demographics only — it is not compatible with tv_viewership_by_program's demo parameter. 3. LIST SEGMENTS (group=...): returns the individual demo_no segments inside a group. Accepts the group name (exact) or its demo_group_no. E.g. group="Political In-State NE v3 - 08.27.2018 to Ongoing" returns the NE voter segments (Democratic/Republican/Independent turnout tiers) with their demo_no. demo_local=true on a segment means the same tv_demographics-only restriction applies as for groups. A resolved group name is accepted directly by tv_demographics(demo_groups=[...]) for an audience breakout, as are individual demo_no values. A free-text `name` fragment also works for a substring search across all demo names (e.g. "Hispanic", "WSIL"); results include the owning group for context. It matches the name as written, so search on one distinctive word and read the matches rather than combining words that may never appear together in a demo name. When no owner/group matches, the requested segment is not available in TV data. A fourth mode covers reverse ID lookup: 4. RESOLVE IDS (demo_nos=[...]): returns metadata for each demo_no — for feed/Snowflake-share clients that arrive with raw demo_no values and need the names back. Args: name: Optional free-text fragment for a fuzzy demo_name search. owner: Optional exact owner family name to list its groups (mode 2). Known owners include: Comscore Political Segments, Comscore Automotive - Local, Comscore Automotive - National, Comscore Plan Metrix. group: Optional group name (exact) or demo_group_no to list its member segments (mode 3). demo_nos: Optional list of demo_no values to resolve back to names/metadata (mode 4). Standard demos (no lookup needed; pass directly to high-level tools). "Persons N-M" and "AN-M" are different demographics — Persons demos measure people in the age range, A/M/W demos measure households containing someone in it — so pass whichever the request actually names, never the other: HH: household metrics (no demo_no). Persons: Persons 2+ / P2+=83841, Persons 18-49=83844, Persons 18+=83845, Persons 25-54=83849 (also Female/Male Persons variants, e.g. Male Persons 25-54=83885 — search by name for the rest). HHs w/ age range ("households 25-54" = A25-54): A18-34=651, A18-49=3623, A25-49=5053, A25-54=652, A18+=46524, M18-49=3632, M25-49=3633, M25-54=3634, M18+=46525, W18-49=3641, W25-49=3642, W25-54=3643, W18+=46526.

tv_search_demographics

Find a Comscore TV market by name fragment to get its market_no, or resolve a list of market_no IDs back to market metadata. Resolves a market name like "Abilene, TX" or "New York" to the market_no that local TV queries take. Pass "all" (or leave `name` empty) to list every Comscore market — never enumerate the footprint with letter-by-letter searches, and note that the viewership tools take markets=["all"] directly, so covering every market needs no lookup at all. Pass `market_nos` instead of `name` to reverse-resolve raw market_no values (e.g. from a Snowflake share or a data feed) back to market metadata. Every row carries `universe`, the market's household Universe Estimate (UE), and rows come back largest first — so the first rows are the biggest markets. To rank or filter markets by audience size, use `universe` (e.g. the top 25 markets, or markets above 500,000 households). It is a household count; a per-demographic UE by market is not available here. In every output — prose, headings, table columns, chart labels, and any Word/PPTX/PDF export — label these "Comscore market" (or "CM" after first use). No other market/region term or acronym is permitted. Args: name: Market name fragment (case-insensitive), e.g. "Abilene", "Boston", "New York". Empty or "all" returns every Comscore market. market_nos: Optional list of market_no values to resolve back to metadata. Mutually exclusive with a non-empty `name`. as_of: Optional YYYY-MM-DD date the `universe` is read for. Defaults to today; the API has no universe for dates in the future.

tv_search_markets

Resolves a TV network name to its network_no ID, or a set of network_no IDs back to names. Pass either `name` (fuzzy substring on network_name, or a call sign such as "FNC"/"FOXNC") or `network_nos` (exact reverse lookup by ID). Exactly one must be given. Args: name: Name fragment or call sign (case-insensitive), e.g. "CNN", "NBC", "ESPN". network_nos: List of network_no values to resolve back to names/metadata.

tv_search_networks

Finds a specific local TV station by call sign or name to get its station_no, or resolves a list of station_no IDs back to station metadata (reverse lookup). Covers both broadcast affiliates (positive station_no) and cable networks (negative station_no). Pass either `name` (fuzzy match on call sign / station name, active stations only) or `station_nos` (exact reverse lookup by ID — for feed/Snowflake-share clients arriving with raw IDs; includes inactive stations so historical IDs still resolve). Args: name: Call sign or name fragment to search for (case-insensitive). Examples: "GBTS", "WBZ", "WCVB", "NBC", "Boston CBS", "crmz". market_no: Optional — restrict `name` results to stations whose primary market matches this market_no. Ignored when `station_nos` is given. tv_search_markets resolves a market name to market_no. station_nos: List of station_no values to resolve back to metadata (batched internally when large). Example — find GBTS in Boston: tv_search_stations(name="GBTS") # by call sign tv_search_stations(name="NBC", market_no=2009) # NBC affiliates in Boston tv_search_stations(station_nos=[4616, -54988, 14285]) # reverse ID lookup

tv_search_stations

Station demographic breakdown or national HH/demo universe estimates. TWO MODES: 1. Station Demographic Breakdown (set universe_estimates=False, default): Returns avg_aud by demographic group (income, race, education, country of origin). Requires markets or stations + period. 2. National HH/Demo Universe Estimates (set universe_estimates=True): Returns national_demo_universe for demographic groups. Use year + month instead of period. Args: period: Period string (mode 1). E.g. "Specific Time Range;2024-April-03-2024-April-09". markets: Market names (mode 1). In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. stations: Station call signs or names (mode 1). dayparts: Daypart filters (mode 1), e.g. ["All Week", "Weekdays"]. demo_groups: Demographic group names to look up. Examples: Mode 1: ["HHs W/ Race/Ethnicity", "Household Income", "Country of Origin", "HHs W/ Education"] Mode 2: ["A18+", "M18+", "W18+", "English more than Spanish", "Dog - Yes"] Also accepts a custom SEGMENT GROUP name or demo_group_no discovered via tv_search_demographics (e.g. "Political In-State NE v3 - 08.27.2018 to Ongoing" or 8541) — it resolves to the group's member segments automatically. Local-flagged groups break out per market; national-only groups will not return local data. universe_estimates: True → national universe estimates mode. year: Year for universe estimates mode (e.g. 2024). month: Month name for universe estimates mode (e.g. "April"). Examples: # Station demographic breakdown — WABC, race/ethnicity tv_demographics( stations=["WABC New York, N.Y. (ABC)"], period="Specific Time Range;2024-April-03-2024-April-09", dayparts=["All Week"], demo_groups=["HHs W/ Race/Ethnicity"], ) # National HH demo universe estimates tv_demographics( universe_estimates=True, demo_groups=["A18+", "M18+", "W18+"], year=2023, month="October", )

tv_demographics

Network viewership broken down by market — National Market widget. Args: period: Period string, e.g. "Specific calendar month;2023-November". markets: Market names, e.g. ["Portland, ME", "Abilene, TX"]. In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. networks: Network names, e.g. ["ABC", "A&E"]. None = all networks. metrics: Default: ["avg_aud", "rating", "num_hours"]. Options: "avg_aud", "rating", "num_hours", "market_index" (market vs national rating ratio ×100), "hh_universe" (household universe count), "market_rank" (market rank number). "Total Hours Viewed" → "num_hours"; "Market Index" → "market_index"; "Household Universe" → "hh_universe"; "Market Rnk"/"Market #" → "market_rank". group_by: Dimensions, e.g. ["market", "network"] (default), ["network"] (aggregate all selected markets per network), ["market"] (aggregate across networks per market), ["network", "day_of_week"]. When grouped by both market and network, a market-total rollup row (network_name "(N networks)") is inserted above each market's network rows. Example: tv_market_viewership( markets=["Portland, ME", "Abilene, TX"], networks=["ABC", "A&E"], period="Specific calendar month;2023-November", metrics=["avg_aud", "rating", "num_hours", "market_index"], group_by=["market", "network"], )

tv_market_viewership

Program schedule — what aired on a station/network on a given day. Covers: Station Schedule widget. Scope: provide markets, stations, or networks (at least one). markets: Fetch schedule for all stations in these markets. stations: Specific station call signs or names. networks: Network name for national schedule lookup. Args: day: Date string, e.g. "2024-July-01" or "2024-07-01". fields: Columns to return (user-friendly OR API names). Default: all available. User-friendly → API name mappings: "Air Date" → "day" (broadcast date, formatted as 'Mon DD, YYYY') "Air Time" → "airdatetime" (broadcast start time, H:MM AM/PM local) "Run Time" → "duration_minutes" (program length in minutes, integer) "Series Name" → "series_name" "Episode Title" → "episode_title" Other API fields: "episode_no", "is_new_airing", "series_genre". NOTE: "Run Time" = duration in MINUTES (e.g. 30, 60), i.e. program length — not a time of day. "Air Time" is the broadcast clock time. Examples: # Station schedule for ABC network on July 1 2024 tv_schedule(networks=["ABC"], day="2024-July-01", fields=["Run Time", "Series Name"]) # Schedule for a specific station with Air Date, Air Time, Run Time, Series Name, Episode Title tv_schedule(stations=["ERC Washington, D.C. (Cozi TV)"], day="2025-July-01", fields=["Air Date", "Air Time", "Run Time", "Series Name", "Episode Title"])

tv_schedule

Program-level viewership ranked by audience. Covers: Local Ranker, Local Program-Based, National Ranker, National Program-Based, National Ad Report, Syndicated Series Reporting. Scope (provide at least one, or omit all for all national networks): markets: Market names, e.g. ["Abilene, TX", "Buffalo, NY"], or ["all"] for every Comscore market (no market lookups needed). Automatically fetches all stations in those markets. In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. stations: Station call signs or names, e.g. ["WABC", "KRBC Abilene, Texas (NBC)"] Can mix with markets. networks: Network names or call signs for national path, e.g. ["ABC", "A&E", "FNC"] Mutually exclusive with markets/stations. Args: period: "Specific broadcast month;2023-February" — that's the format. Other examples: "Specific calendar month;2023-November" "Specific Time Range;2024-March-13-2024-March-14" "Specific Day;2024-July-01" dayparts: Daypart names or clock hours, e.g. ["Prime", "14:00", "3am to 3am"]. Named: "Early Morning", "Daytime", "Early Fringe", "Prime Access", "Prime"/"Broadcast Prime", "Late Fringe", "Overnight". Clock hour: "02:00PM", "14:00", "07:00AM" → 1-hour window each. Multiple clock hours: pass each as a separate list item, e.g. ["12:00AM", "01:00AM"] for midnight-2am coverage (two 1-hour windows). Semicolon-separated string also works: "12:00AM;01:00AM". "3am to 3am" / "6am to 6am" / "All Week" = total day (no filter). days_of_week: Day filters, e.g. ["Monday", "Weekdays", "Friday"]. Can also be included in dayparts list. station_types: Which stations a `markets` scope expands to. Default (omitted) = local over-the-air broadcast stations only. Options: "broadcast" (OTA), "cable" (national cable feeds as carried in those markets — the only way to get cable viewing for a market), "independent", "all". dimension: What to rank rows by: "series" (default), "station", "network", "telecast", "newscasts", "genre". "station" (local) averages over the station's scheduled program airings, which is the Comscore Reporting Hub's Ranker figure. For a small or partly carried station that is far higher than its all-day average (a station on air a few hours a day, or only partly programmed, can read 2x-17x higher). For the plain "average audience of this station over the period" (the Time- Based trender figure) call tv_viewership_by_time with granularity="period" instead. "genre" (local) returns one row per program genre per market (e.g. Sports, News, Drama) with the stations rolled up. "series" aggregates each program to one row across the whole period — use this for "top N programs" questions. "telecast" returns one row per individual airing (each date + start_time is a separate row, so one program can appear dozens of times) — only use this when the request is specifically about individual broadcasts/airdates, not an aggregated ranking. demo: Demographic, e.g. "HH" (default), "A18-49", "W25-54", "M18-49". Pass the demographic the request NAMES, verbatim. "Persons 25-54" and "A25-54" are different demographics, not two spellings of one: Persons demos count people in the age range, A/M/W demos count households containing someone in it. A request for persons must be passed as "Persons 25-54" (likewise "Persons 18-49", "Persons 18+", "Male Persons 25-54", ...) — substituting the A-label silently returns another population's numbers. "Households 25-54" means A25-54. If the demo can't be resolved, ask the user — never run another one. Multiple demos can be requested in a single call by separating them with semicolons, e.g. "A18-34;A18-49;A25-54;A55+". The first demo uses the bare metric name (e.g. avg_aud, rating); each additional demo gets its own column suffixed with the demo label, e.g. avg_aud_A18-49, rating_A55+, returning all demos in a single call. Custom segment IDs from tv_search_demographics (e.g. a Political, Automotive, or Plan Metrix demo_no) cannot be used here directly — pass them via demo_groups instead (see below). demo_groups: Cross-tab program rankings by a custom segment group discovered via tv_search_demographics — e.g. a Comscore Automotive, Political, or Plan Metrix group name/demo_group_no (owner "Comscore Automotive - Local" → group "Intent to Buy - Rollup Segments" → individual segments like "New Pickup"), or an individual demo_no/demo_name. Look up the exact group or segment first with tv_search_demographics — group/segment names are not guessable. Each entry adds an avg_aud/rating/share column for that segment alongside the primary demo (same one-column-per-demo pattern as semicolon-separated `demo` values) — rows stay grouped by the `dimension` (e.g. one row per program), now cross-tabbed with segment reach. Local-only groups only return data on local (markets/stations) queries; national-only groups only return data on the networks path. Segment pct/index values from the same owner family (e.g. multiple Automotive groups) can overlap and are not additive. metrics: Metrics to return. Default: ["avg_aud", "rating", "share", "num_hours"]. Options: "avg_aud", "rating", "share", "num_hours", "demo_index" (the native "Demo Index" field — Demo Rating / HH Rating x100 — pass "Index" or "demo_index" directly; do not ask the user to choose a definition, this is the one canonical Demo Index), "ad_rating", "ad_grps", "ad_avg_aud", "ad_gross_aud", "ad_to_telecast_index", "num_airings", "ad_num_airings" (national ad report only). The bare ad_rating / ad_grps / ad_avg_aud / ad_gross_aud columns are household values; each requested demographic adds its own column (ad_rating_A18-24, ad_avg_aud_A18-24, ...), so read the demo's value from there. Syndicated series: "daily_aa", "gross_aa", "weighted_aa", "available_hours", "series_no" (routes to local_syndicated_views). Every row also always includes meets_demo_threshold and meets_high_quality_demo_threshold for each non-HH demo requested (true/false) — surface these to flag suppressed/low-confidence figures (below 300 HH/25 hrs, or below 75 HH for the high-quality bar). The API only computes these for a demographic, so an HH-only request (demo="HH", the default) won't return them. stream: "live" (default), "live+sd", "live+1", "live+2", "live+3", "live+7". Local queries also take a list to compare several streams in ONE call — each metric then comes back as <metric>_<stream> columns (avg_aud_live_sd, rating_live_2, ...) and rows rank by the first stream. Any other value is rejected with an error. Works on national and local endpoints (program viewing: live plus DVR playback within the window). Defaulting to "live" only counts live viewing — DVR/time- shifted playback is excluded unless requested. A response note flags when time-shifted figures are also available for the query but weren't requested. series_filter: {"include": ["Series Name"]} or {"exclude": ["Series Name"]} to filter by specific series. Names are checked against the series catalog first: case differences are matched, and a name that fits several series returns the candidates to ask the user about. Local-station program names come from each station's own listings, so they can be abbreviated or differ from the network's name for the same show (e.g. "News4 NY at 11AM"); report them verbatim. extra_periods: Additional period strings to include alongside the primary period. Use for "Extra Period" comparison periods. Pass the raw value from the prompt including the "Extra Period;" prefix if present, e.g. ["Extra Period;2023-November-25-2023-November-26"] or without the prefix: ["2023-November-25-2023-November-26"]. Results from all periods are combined into a single OR date filter. breakout: Optional secondary breakout dimension that splits each program row into one row per value, instead of aggregating over the whole period. "week" — per-week pivot (the "Series;Week" column pivot): each program gets a row per broadcast week with that week's share/index, rather than a period average. "daypart" — one row per daypart passed in `dayparts`, in a SINGLE request. Without it, multiple dayparts aggregate into one combined number, so a per-daypart report needs one call per daypart; use it whenever a request asks for several dayparts broken out (e.g. all 7 standard dayparts). Currently supported on local program queries. limit: Maximum rows to return in total (default 100), max 10000. Increase for full rankings, decrease for top-N queries. A scope over 300 stations is split into batched requests and merged; `limit` applies once, to that merged total, not per batch — raising it never shrinks any individual batch. Examples: # Local Ranker — station dimension, Abilene TX, Feb 2023 broadcast month, 2PM tv_viewership_by_program( markets=["Abilene, TX"], period="Specific broadcast month;2023-February", dayparts=["02:00PM"], dimension="station", demo="HH", stream="live+3", ) # National Ranker — series on A&E, October 2023, Friday overnight tv_viewership_by_program( networks=["A&E"], period="Specific calendar month;2023-October", dayparts=["Friday", "Overnight"], dimension="series", demo="A18+", ) # Program x automotive-segment cross-tab — top programs on Chicago # stations for the "New Pickup" in-market truck-buyer segment, June 2024. # Look up the exact segment/group name first with tv_search_demographics # (e.g. owner="Comscore Automotive - Local", then # group="Intent to Buy - Rollup Segments" to find "New Pickup"). tv_viewership_by_program( markets=["Chicago, IL"], period="Specific calendar month;2024-June", dimension="series", demo_groups=["New Pickup"], ) # Demo Index — "show me the demo index for WLS in Chicago last June" # maps straight to metrics=["demo_index"]. Demo Index is a native field # on the TV data, so never ask which index the user means or how they # want it defined; just request it alongside whatever else is wanted. tv_viewership_by_program( markets=["Chicago, IL"], period="Specific calendar month;2024-June", dimension="station", demo="A25-54", metrics=["avg_aud", "rating", "demo_index"], ) # Station x daypart report — every station in two markets, all 7 standard # dayparts as separate rows, in one call (breakout="daypart"). tv_viewership_by_program( markets=["New York, NY", "Los Angeles, CA"], period="Specific broadcast month;2025-November", dayparts=["Early Morning", "Daytime", "Early Fringe", "Prime Access", "Prime", "Late Fringe", "Overnight"], dimension="station", demo="HH;A25-54", metrics=["avg_aud", "rating", "num_hours"], breakout="daypart", limit=5000, )

tv_viewership_by_program

Time-slot viewership — ratings by quarter-hour, hour, day, or daypart. Covers: Local Time-Based, National Time-Based, Local Trender (Chart), National Trender (Chart), Time-Based Grid widgets. Scope (provide at least one, or omit for all national networks): markets: Market names, e.g. ["Abilene, TX"], or ["all"] for every Comscore market (no market lookups needed). In output, label these "Comscore market" (or "CM" after first use) — never any other market/region term. stations: Station call signs or names, e.g. ["KRBC Abilene, Texas (NBC)"] networks: Network names or call signs for national path, e.g. ["AMC", "FNC"] Args: period: Period string (same formats as tv_viewership_by_program). dayparts: Daypart names or clock hours to filter to. Days of week can also be included here. Include "3am to 3am" to start the broadcast day at 3am: the named dayparts then use their 3am windows (Early Morning 3-9am) and 03:00-05:45 rows are returned. Without it the day starts at 6am and Early Morning begins at 6am. Named dayparts cover all seven days; a Time-Based Grid in the Comscore Reporting Hub shows Monday-Friday, so add "Weekdays" to match it. days_of_week: Day filters (can also go in dayparts). station_types: Which stations a `markets` scope expands to. Default (omitted) = local over-the-air broadcast stations only. Options: "broadcast" (OTA), "cable" (national cable feeds as carried in those markets — the only way to get cable viewing for a market), "independent", "all". granularity: Time resolution for rows: "qtr_hour" (default) — one row per 15-minute slot "hour" — one row per hour "day" — one row per broadcast day (Trender) "week" — one row per week "period" — one row per station / network for the WHOLE period, averaged over every quarter-hour (inside the dayparts, if given). This is the Comscore Reporting Hub's Time-Based audience for a station, and the right call for "average audience of station X over the period": small or partly carried stations come out far lower here than in tv_viewership_by_program(dimension="station"), which averages only over scheduled program airings. "daypart" — one row per daypart passed in `dayparts`, all from a SINGLE request. Without it, multiple dayparts collapse into one combined number, so a per-daypart report needs one call per daypart. Use it whenever a request wants several dayparts broken out (e.g. all 7 standard dayparts). demo: Demographic, e.g. "HH", "A18-49". Pass the demographic the request NAMES, verbatim: "Persons 25-54" (people in the range) and "A25-54" (households containing someone in it) are different demographics, so substituting one for the other silently returns another population's numbers. "Households 25-54" means A25-54. If the demo can't be resolved, ask the user — never run another one. Multiple demos can be requested in one call by separating with semicolons, e.g. "A18-34;A18-49;A55+" — each gets its own column suffixed with the demo label (rating_A18-49, avg_aud_A55+, ...), returning all demos in a single call. For BOTH "household metrics" and "demographic metrics" together (e.g. household "Live Share" + demographic "Share" with a stated demographic like A18+), demo="HH;A18+" combines them: the HH column covers the household metric and the demo column covers the demographic metric. metrics: Default: ["avg_aud", "rating"]. Options: "avg_aud", "rating", "share", "num_hours", "sets_in_use" (the "Sets In Use" / "SIU" / "QH SIU" metric — pass "Sets In Use" or "sets_in_use"). Like share, sets_in_use emits one column per demo (HH → "sets_in_use", demo → "sets_in_use_<demo>"). Every row also always includes meets_demo_threshold and meets_high_quality_demo_threshold for each non-HH demo requested (true/false) — surface these to flag suppressed/low-confidence figures (below 300 HH/25 hrs, or below 75 HH for the high-quality bar). The API only computes these for a demographic, so an HH-only request (demo="HH", the default) won't return them. stream: "live" (default), "live+sd", "live+1", "live+2", "live+3", "live+7". Pass a list to compare several streams in ONE call — each metric then comes back once per stream as <metric>_<stream> columns (avg_aud_live, avg_aud_live_sd, rating_live_3, ...). share has no per-stream value. Any other value is rejected with an error. aggregate_stations: Collapse all stations in scope into one row per market (per time slot / daypart) by summing their audience — e.g. a single per-market "Cable" total with station_types=["cable"]. The row carries a `stations` count. Sums avg_aud / rating / share / num_hours (all additive over a market's stations); Sets In Use is a market-level level, so its maximum is kept rather than a sum. Local (markets/stations) queries only. limit: Maximum rows to return in total (default 100). Increase to fetch a full trender/time-grid. A scope over 300 stations is split into batched requests and merged; `limit` applies once, to that merged total, not per batch — raising it never shrinks any individual batch. Bulk-pull exception: `granularity="daypart"` on a batched scope (a full-footprint pull) returns EVERY (station, daypart) row and ignores `limit` — capping there would silently drop stations, and the caller would have to shard the market list by hand to get the whole answer. For a top-N program ranker with daypart breakout, use `tv_viewership_by_program(breakout="daypart", limit=N)`. Examples: # Local Time-Based — KRBC Abilene, quarter-hour, March 2024 tv_viewership_by_time( stations=["KRBC Abilene, Texas (NBC)"], period="Specific Time Range;2024-March-29-2024-March-30", dayparts=["6am to 6am", "Weekdays"], granularity="qtr_hour", ) # Local Trender — all stations in Abilene, by hour, broadcast week June 2025 tv_viewership_by_time( markets=["Abilene, TX"], period="Specific broadcast week;Week: 25 - (16-June-2025 - 22-June-2025)", granularity="hour", demo="A18-24", ) # National Time-Based — AMC, qtr-hour, Jan 2023, Wednesday midnight. # Request asks for household Share AND A18+ Share → pass both demos so # the result has an HH share column ("share") and an A18+ column ("share_A18+"). tv_viewership_by_time( networks=["AMC"], period="Specific Time Range;2023-January-17-2023-January-18", dayparts=["Wednesday", "12:00AM"], granularity="qtr_hour", demo="HH;A18+", metrics=["share"], ) # Station x daypart pull — every broadcast station in every market, all 7 # standard dayparts as rows, HH + Persons 25-54, in one call. The >300 # stations are batched automatically. tv_viewership_by_time( markets=["New York, NY", "Los Angeles, CA", ...], period="Specific broadcast month;2025-November", dayparts=["Early Morning", "Daytime", "Early Fringe", "Prime Access", "Prime", "Late Fringe", "Overnight"], granularity="daypart", demo="HH;Persons 25-54", metrics=["avg_aud", "rating", "num_hours"], limit=5000, ) # Per-market cable total by daypart — one aggregated "Cable" row per market. tv_viewership_by_time( markets=["Abilene, TX"], period="Specific broadcast month;2025-November", dayparts=["Prime", "Daytime"], station_types=["cable"], granularity="daypart", aggregate_stations=True, metrics=["avg_aud", "rating", "num_hours"], )

tv_viewership_by_time