Nielsen National TV Analytics API Beta Technical Reference Authorization API POST Request URL: https://api.developer.nielsen.com/watchapi/oauth/token Header Name Authorization (required) string Base64 encoded string of <Client ID>:<Client Secret>. Basic <Base64 Encoded String> Content- (required) string application/x-www-form-urlencoded Form Name grant_type (required) string password username (required) string Username provided by Nielsen. password (required) string Password provided by Nielsen. Data Availability API GET Request URL: https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/dataavailability Header Name Authorization (required) string API access token provided by Nielsen. Bearer <access token> Response Field data originator datastream Description A description of the type of data reported. Program (Program ratings) of originator. Cable Broadcast Syndication Time-shifted viewing from DVR Playback or On-demand content with the same commercial load. Live (Live - Includes viewing that occurred during the live airing). Live+SD (Live + Same Day - Includes all playback that
earliestavailability latestavailability occurred within the same day Live+3 (Live + 3 Days - Includes all playback that occurred within three days Live+7 (Live + 7 Days - Includes all playback that occurred within seven days The earliest reportable date (YYYY-MM-DD). The most recent reportable date (YYYY-MM-DD). Originators API GET Request URL: https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/originators Header Name Authorization (required) string API access token provided by Nielsen. Bearer <access token> Parameter Name originator (required) String of originator. Cable Broadcast Syndication sample (required) string The source panel from which viewing is collected. National Hispanic startdate string The first day of the measurement interval (YYYY- MM-DD). enddate string The last day of the measurement interval (YYYY- MM-DD). Response Field originator originator Description Abbreviated originator name (e.g. ABC ). of originator. Cable Broadcast Syndication Program Ratings API GET Request URL: https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/programratings
Header Name Authorization (required) string API access token provided by Nielsen. Bearer <access token> Parameter Name sample (required) string The source panel from which viewing is collected. National Hispanic startdate (required) string The first day of the measurement interval (YYYY- MM-DD). enddate (required) string The last day of the measurement interval (YYYY- MM-DD). daypartid string A unique character identifier for an individual daypart; sourced from the Dayparts API, response field daypartid. EF (Early Fringe - M-Sa 6P - 8P, Su 6P - 7P) WKM (Weekday Morning - M-F 6A - 10A) WKD (Weekday Daytime - M-F 10A - 6P) PRI (Prime Time - M-Sa 8P - 11P, Su 7P - 11P) LF (Late Fringe - M-Su 11P - 6A) WED (Weekend Daytime - Sa-Su 6A - 6P) starttime string The start time (HH:MM) of the daypart. endtime string The end time (HH:MM) of the daypart. demographics (required) string A comma separated list of Demographics. The input values should demoabbreviation values and age ranges. For example: Household Persons 18-49 Males 35-54 Females 55-999 originators (required) string A comma separated list of originators; sourced from the Originators API. datastreams (required) string A comma separated list of data streams. Time-shifted viewing from DVR Playback or Ondemand content with the same commercial load. Live (Live - Includes viewing that occurred during the live airing).
Live+SD (Live + Same Day - Includes all playback that occurred within the same day Live+1 (Live + 1 Day Includes all playback that occurred within one day of the live airing). Live+2 (Live + 2 Days Includes all palyback that occurred within two days Live+3 (Live + 3 Days - Includes all playback that occurred within three days Live+4 (Live + 4 Days Includes all playback that occurred within four days Live+5 (Live + 5 Days Includes all playback that occurred within five days Live+6 (Live + 6 Days Includes all playback that occurred with six days of the live airing). Live+7 (Live + 7 Days - Includes all playback that occurred within seven days mediasources (required) string The contributing platform for viewing. TVwithDigital TV Digital Computer Mobile Tablet Smartphone PortableMediaPlayer Others contribution (required) string The contributing viewing from VOD with the same ad load as linear telecast. LinearWithVOD Linear VOD ratingmetrics string A comma separated list of rating metrics. No specification will return all metrics. usaapercentage (Total U.S. Average Audience Percentage = The percentage of the target demographic viewing the average minute of the selected program or time period within the total U.S.) usaaprojunits (Total U.S. Average
Audience Projection (Units) = The projected number of households tuned or persons viewing a program/originator/daypart during the average minute) usaaproj000 (Total U.S. Average Audience Projection (000) = The projected number of households tuned or persons viewing a program/originator/daypart during the average minute, expressed in thousands) ussharepercentage (Total U.S. Share Percentage = The percentage of households tuning or persons viewing that are tuned to a specific program/originator/daypart) ushutputpercentage (Total U.S. Households Using Television/Persons Using Television Percent = The percentage of all televisions households within the total U.S. using their television sets during the average minute of a specific time period) ushutputprojunits (Total U.S. Households Using Television/Persons Using Television Projection (Units) = The projected estimates of all television households within the total U.S. using their television sets during the average minute of a specific time period) ushutputproj000 (Total U.S. Households Using Television/Persons Using Television Projection (000) = The projected estimates of all television households within the total U.S. using their television sets during the average minute of a specific time period, expressed in thousands) usaavpvh0000 (Viewers Per Viewing Household = The projected number of viewers per 10,000 projected households passing person edits for the average minutes of a selected program or time period. In other words, it is the number of viewing persons per tuning household.)
cvgaapercentage (Coverage Area Average Audience Percent = The percentage of the target demographic viewing the average minute of a selected program or time period within a network s coverage area) usue000 (The Universe Estimate (UE) is the total number of households or persons within the target demographic across the total U.S.) cvgue000 (The Coverage Universe Estimate is the total number of households or persons within the target demographic across the network s coverage area.) usintab (U.S. Intab = The number of households or persons supplying usable information within the television panel across the total U.S.) Response Field broadcastdate programid telecastid originator trackagename summarycode daypartid reportedduration telecastreportstarttime calendardayofweekname telecastreportendtime originator Description The date on which the telecast originally aired (YYYY-MM-DD). A unique numerical identifier for an individual program name. A unique numerical identifier for an individual telecast. Abbreviated originator name. (e.g. ABC ). A unique identifier provided by the client to track each telecast (e.g. NCIS MARA TH 3P tracks airings of NCIS that occurred on Thursdays at 3PM). A unique character identifier for the top-level genre classification (e.g. GD = General Drama). A unique character identifier for an individual daypart. EF (Early Fringe - M-Sa 6P - 8P, Su 6P - 7P) WKM (Weekday Morning - M-F 6A - 10A) WKD (Weekday Daytime - M-F 10A - 6P) PRI (Prime Time - M-Sa 8P - 11P, Su 7P - 11P) LF (Late Fringe - M-Su 11P - 6A) WED (Weekend Daytime - Sa-Su 6A - 6P) The duration of the program/telecast airing (minutes). The start time of the telecast (HH:MM). The day of the week during which the program aired (e.g. THURSDAY ). The end time of the telecast (HH:MM). of originator Cable Broadcast Syndication
programname episodetitle contribution mediasource datastream marketbreakid marketbreak marketsection demographic usaapercentage Full program name. A title for an individual episode of a program. The contributing viewing from VOD with the same ad load as linear telecast. LinearWithVOD Linear VOD The contributing platform for viewing. TVwithDigital TV Digital Computer Mobile Tablet Smartphone PortableMediaPlayer Others Time-shifted viewing from DVR Playback or On-demand content with the same commercial load. Live (Live - Includes viewing that occurred during the live airing). Live+SD (Live + Same Day - Includes all playback that occurred within the same day Live+1 (Live + 1 Day Includes all playback that occurred within one day Live+2 (Live + 2 Days Includes all palyback that occurred within two days Live+3 (Live + 3 Days - Includes all playback that occurred within three days Live+4 (Live + 4 Days Includes all playback that occurred within four days Live+5 (Live + 5 Days Includes all playback that occurred within five days Live+6 (Live + 6 Days Includes all playback that occurred with six days Live+7 (Live + 7 Days - Includes all playback that occurred within seven days A unique numerical identifier for a Market Break. An audience segment based on household characteristics (e.g. Household Income 125K+, Household Size 2, etc.) A category of audience segments based on household characteristics. The target demographic. Total U.S. Average Audience Percentage (The percentage of the target demographic viewing the average minute of the selected program or time period within the total U.S.)
usaaprojunits usaaproj000 ussharepercentage ushutputpercentage ushutputprojunits ushutputproj000 usaavpvh0000 cvgaapercentage usue000 cvgue000 usintab Total U.S. Average Audience Projection (Units) (The projected number of households tuned or persons viewing a program/originator/daypart during the average minute.) Total U.S. Average Audience Projection (000) (The projected number of households tuned or persons viewing a program/originator/daypart during the average minute, expressed in thousands.) Total U.S. Share Percentage (The percentage of households tuning or persons viewing that are tuned to a specific program/originator/daypart.) Total U.S. Households Using Television/Persons Using Television Percent (The percentage of all television households within the total U.S. using their television sets during the average minute of a specific time period.) Total U.S. Households Using Television/Persons Using Television Projection (Units) (The projected estimates of all television households within the total U.S. using their television sets during the average minute of a specific time period.) Total U.S. Households Using Television/Persons Using Television Projection (000) (The projected estimates of all television households within the total U.S. using their television sets during the average minute of a specific time period, expressed in thousands.) Viewers Per Viewing Household (The projected number of viewers per 10,000 projected households passing person edits for the average minutes of a selected program or time period. In other words, it is the number of viewing persons per tuning household.) Coverage Area Average Audience Percent (The percentage of the target demographic viewing the average minute of a selected program or time period within a network s coverage area.) The Universe Estimate (UE) is the total number of households or persons within the target demographic across the total U.S. The Coverage Universe Estimate is the total number of households or persons within the target demographic across the network s coverage area. U.S. Intab (The number of households or persons supplying usable information within the television panel across the total U.S.) Commercial Ratings API GET Request URL: https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/commercialratings Header Name Authorization (required) string API access token provided by Nielsen. Bearer <access token>
Parameter Name sample (required) string The source panel from which viewing is collected. National Hispanic startdate (required) string The first day of the measurement interval (YYYY- MM-DD). enddate (required) string The last day of the measurement interval (YYYY- MM-DD). daypartid string A unique character identifier for an individual daypart; sourced from the Dayparts API, response field daypartid. EF (Early Fringe - M-Sa 6P - 8P, Su 6P - 7P) WKM (Weekday Morning - M-F 6A - 10A) WKD (Weekday Daytime - M-F 10A - 6P) PRI (Prime Time - M-Sa 8P - 11P, Su 7P - 11P) LF (Late Fringe - M-Su 11P - 6A) WED (Weekend Daytime - Sa-Su 6A - 6P) starttime string The start time (HH:MM) of the daypart. endtime string The end time (HH:MM) of the daypart. demographics (required) string A comma separated list of Demographics. The input values should demoabbreviation values and age ranges. For example: Household Persons 18-49 Males 35-54 Females 55-999 originators (required) string A comma separated list of originators; sourced from the Originators API. datastreams (required) string A comma separated list of data streams. Time-shifted viewing from DVR Playback or Ondemand content with the same commercial load. Live (Live - Includes viewing that occurred during the live airing). Live+SD (Live + Same Day - Includes all playback that occurred within the same day Live+1 (Live + 1 Day Includes all
playback that occurred within one day of the live airing). Live+2 (Live + 2 Days Includes all palyback that occurred within two days Live+3 (Live + 3 Days - Includes all playback that occurred within three days Live+4 (Live + 4 Days Includes all playback that occurred within four days Live+5 (Live + 5 Days Includes all playback that occurred within five days Live+6 (Live + 6 Days Includes all playback that occurred with six days of the live airing). Live+7 (Live + 7 Days - Includes all playback that occurred within seven days mediasources (required) string The contributing platform for viewing. TVwithDigital TV Digital Computer Mobile Tablet Smartphone PortableMediaPlayer Others contribution (required) string The contributing viewing from VOD with the same ad load as linear telecast. LinearWithVOD Linear VOD ratingmetrics string A comma separated list of rating metrics. Specifies the metrics provided in the API response. nccmusaapercentage (National Commercial Clock Minute Average Audience Percentage = The percentage of the target demographic viewing the average qualified commercial minute of the selected program within the total U.S.) nccmusaaprojunits (National Commercial Clock Minute Average
Audience Projection (Units) = The projected number of households tuned or persons viewing the average qualified commercial minute of the selected program within the total U.S.) nccmusaaproj000 (National Commercial Clock Minute Average Audience Projection (000) = The projected number of households tuned or persons viewing the average qualified commercial minute of the selected program within the total U.S., expressed in thousands) nccmcvgaapercentage (National Commercial Clock Minute Coverage Area Average Audience Percent = The percentage of the target demographic viewing the average qualified commercial minute of a selected program within a network s coverage area) usue000 (The Universe Estimate (UE) is the total number of households or persons within the target demographic across the total U.S.) cvgue000 (The Coverage Universe Estimate is the total number of households or persons within the target demographic across the network s coverage area.) usintab (U.S. Intab = The number of households or persons supplying usable information within the television panel across the total U.S.) Response Field broadcastdate programid telecastid originator trackagename summarycode daypartid Description The date on which the telecast originally aired (YYYY-MM-DD). A unique numerical identifier for an individual program name. A unique numerical identifier for an individual telecast. Abbreviated originator name. (e.g. ABC ). A unique identifier provided by the client to track each telecast (e.g. NCIS MARA TH 3P tracks airings of NCIS that occurred on Thursdays at 3PM). A unique character identifier for the top-level genre classification (e.g. GD = General Drama). A unique character identifier for an individual daypart.
reportedduration telecastreportstarttime calendardayofweekname telecastreportendtime originator programname episodetitle contribution mediasource datastream EF (Early Fringe - M-Sa 6P - 8P, Su 6P - 7P) WKM (Weekday Morning - M-F 6A - 10A) WKD (Weekday Daytime - M-F 10A - 6P) PRI (Prime Time - M-Sa 8P - 11P, Su 7P - 11P) LF (Late Fringe - M-Su 11P - 6A) WED (Weekend Daytime - Sa-Su 6A - 6P) The duration of the program/telecast airing (minutes). The start time of the telecast (HH:MM). The day of the week during which the program aired (e.g. THURSDAY ). The end time of the telecast (HH:MM). of originator Cable Broadcast Syndication Full program name. A title for an individual episode of a program. The contributing viewing from VOD with the same ad load as linear telecast. LinearWithVOD Linear VOD The contributing platform for viewing. TVwithDigital TV Digital Computer Mobile Tablet Smartphone PortableMediaPlayer Others Time-shifted viewing from DVR Playback or On-demand content with the same commercial load. Live (Live - Includes viewing that occurred during the live airing). Live+SD (Live + Same Day - Includes all playback that occurred within the same day Live+1 (Live + 1 Day Includes all playback that occurred within one day Live+2 (Live + 2 Days Includes all palyback that occurred within two days Live+3 (Live + 3 Days - Includes all playback that occurred within three days Live+4 (Live + 4 Days Includes all playback that occurred within four days
marketbreakid marketbreak marketsection demographic nccmusaapercentage nccmusaaprojunits nccmusaaproj000 nccmcvgaapercentage usue000 cvgue000 usintab cvgintab Live+5 (Live + 5 Days Includes all playback that occurred within five days Live+6 (Live + 6 Days Includes all playback that occurred with six days Live+7 (Live + 7 Days - Includes all playback that occurred within seven days A unique numerical identifier for a Market Break. An audience segment based on household characteristics (e.g. Household Income 125K+, Household Size 2, etc.) A category of audience segments based on household characteristics. The target demographic. National Commercial Clock Minute Average Audience Percentage (The percentage of the target demographic viewing the average qualified commercial minute of the selected program within the total U.S.) National Commercial Clock Minute Average Audience Projection (Units) (The projected number of households tuned or persons viewing the average qualified commercial minute of the selected program within the total U.S.) National Commercial Clock Minute Average Audience Projection (000) (The projected number of households tuned or persons viewing the average qualified commercial minute of the selected program within the total U.S., expressed in thousands.) National Commercial Clock Minute Coverage Area Average Audience Percent (The percentage of the target demographic viewing the average qualified commercial minute of a selected program within a network s coverage area.) The Universe Estimate (UE) is the total number of households or persons within the target demographic across the total U.S. The Coverage Universe Estimate is the total number of households or persons within the target demographic across the network s coverage area. U.S. Intab (The number of households or persons supplying usable information within the television panel across the total U.S.) Coverage Intab (The number of households or persons supplying usable information within the television panel across the network s coverage area.)