National API Technical ReferenceV1.9 - Nielsen API Portal · PDF fileNielsen National TV...
Transcript of National API Technical ReferenceV1.9 - Nielsen API Portal · PDF fileNielsen National TV...
NielsenNationalTVRatingsAPITechnicalReference
NielsenNationalTVRatingsAPIisnotpartofaregularsyndicatedratingserviceaccreditedbytheMRC.NielsenNationalTVRatingsAPIiscurrentlyseekingMediaRatingCouncilaccreditation.
AuthorizationAPIPOSTRequestURL:https://api.developer.nielsen.com/watchapi/oauth/token
HeaderName ParameterType
Description
Authorization(required) string Base64encodedstringof“<ClientID>:<ClientSecret>”.“Basic<Base64EncodedString>”
Content-Type(required) string “application/x-www-form-urlencoded”
FormName ParameterType
Description
grant_type(required) string “password”username(required) string UsernameprovidedbyNielsen.password(required) string PasswordprovidedbyNielsen.
DataAvailabilityAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/dataAvailability
HeaderName ParameterType
Description
Authorization(required) String APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ResponseField DescriptionId Auniquenumericalidentifierforanindividualdatatype/data
releasecombination.dataType Adescriptionofthetypeofdatareported.
• “Program”(Programratings)• “TimePeriod”(Daypartratings)• “Other”(Commercialratings)
reportType Thetypeofreporting.• Program• OvernightProgram
dataRelease Thenameofthedataset.(e.g.“BroadcastPrime(Overnight)”).streamType Time-shiftedviewingfromDVRPlaybackorOn-demandcontent
withthesamecommercialload.• “L”(Live=Includesviewingthatoccurredduringthelive
airing).• “L+SD”(Live+SameDay=Includesallplaybackthat
occurredwithinthesamedayoftheliveairing).• “L+3”(Live+3Days=Includesallplaybackthatoccurred
withinthreedaysoftheliveairing).• “L+7”(Live+7Days=Includesallplaybackthatoccurred
withinsevendaysoftheliveairing).• “C3”(Live+3DaysCommercialRatings=Includesall
playbackofthesamecommercialloadthatoccurredwithinthreedaysoftheliveairing).
reportModel Theunderlyingdatastructure.• TotalProgram
ratingSample Thesourcepanelfromwhichtheratingsmetricsareprojected.• National• Hispanic
latestAvailability Themostrecentreportabledate(YYYY-MM-DD).earliestAvailability Theearliestreportabledate(YYYY-MM-DD).
DaypartsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/dayParts
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ResponseField DescriptiondaypartId Auniquecharacteridentifierforanindividualdaypart.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)• “WKM”(WeekdayMorning-M-F6A-10A)• “WKD”(WeekdayDaytime-M-F10A-6P)• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su6A-6P)
daypartName Fulldaypartname.• “EARLYFRINGE”• “WEEKDAYMORNING”• “WEEKDAYDAYTIME”• “PRIMETIME”
• “LATEFRINGE”• “WEEKENDDAYTIME”
GenresAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/genres
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ResponseField DescriptionsummaryTypeCode Auniquecharacteridentifierforatop-levelgenreclassification
(e.g.“SE”=SportsEvent).summaryTypeDesc Atop-levelgenreclassification(e.g.“SportsEvent”;“Concert
Music”).detailedTypeCode Auniquecharacteridentifierforadetailedgenreclassification(e.g.
“GOPR”=PRO-GOLF).detailedTypeDesc Adetailedgenreclassification(e.g.“PRO-GOLF”;“COLLEGE
BASEBALL-REGULARSEA”).
OriginatorsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/originators
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
sample(required) string Thesourcepanelfromwhichtheratingsmetricsareprojected.
• National• Hispanic
serviceName string Typeoforiginator.• “Cable”• “Broadcast”• “Syndication”
startDate string Thefirstdayofthedesiredreportingperiod(YYYY-MM-DD).
endDate string Thelastdayofthedesiredreportingperiod
(YYYY-MM-DD).
ResponseField DescriptionoriginatorType Typeoforiginator.
• “Cable”• “Broadcast”• “Syndication”
originatorName Fulloriginatorname(e.g.“LIFETIMETELEVISION”). originatorId Auniquenumericalidentifierforanindividualprogramming
originator.
ViewingSourcesAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/viewingSources
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType DescriptionstartDate(required) string Thefirstdayofthedesired
reportingperiod(YYYY-MM-DD).
endDate(required) string Thelastdayofthedesiredreportingperiod(YYYY-MM-DD).
viewingSourceTypes(required) array[string] Thetypeofviewingsource(e.g.AdSupportedCable).
sample(required) string Thesourcepanelfromwhichtheratingsmetricsareprojected.
• National• Hispanic
ResponseField DescriptionviewingSourceId A unique numerical identifier for an individual
viewing source. viewingSourceName Full viewing source name (e.g. “HOME AND
GARDEN TV”). viewingSourceTypeName The type of viewing source (e.g. Ad
Supported Cable).
ProgramsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/programs
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
startDate(required) string Thefirstdayofthedesiredreportingperiod(YYYY-MM-DD).
endDate(required) string Thelastdayofthedesiredreportingperiod(YYYY-MM-DD).
originatorId(required) integer Auniquenumericalidentifierforanindividualprogrammingoriginator;sourcedfromtheOriginatorsAPI,responsefield“originatorId”.
daypartId string Auniquecharacteridentifierforanindividualdaypart;sourcedfromtheDaypartsAPI,responsefield“daypartId”.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su6A-
6P)programName string Aprogramnamefieldwhichreturnspartial
matchesintheresponse.summaryTypeCode string Auniquecharacteridentifierforatop-level
genreclassification;sourcedfromtheGenresAPI,responsefield“summaryTypeCode”.
ResponseField DescriptionprogramId Auniquenumericalidentifierforanindividualprogramname(e.g.
336454=GolfingWorld).programName Fullprogramname.(e.g.SPORTSCENTERLATEL”).summaryTypeCode Auniquecharacteridentifierforatop-levelgenreclassification
(e.g.“SE”=SportsEvent).summaryTypeDesc Atop-levelgenreclassification(e.g.“SportsEvent”;“Concert
Music”).
ReprocessingNotificationsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/reprocessingNotifications
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
startDateTime(required) string Thestarttimeofthereprocessingwindow(YYYY-MM-DDHH:MM:SS).
endDateTime(required) string Theendtimeofthereprocessingwindow(YYYY-MM-DDHH:MM:SS).
serviceName string Typeoforiginator.• “Cable”• “Broadcast”• “Syndication”
originatorId integer Auniquenumericalidentifierforanindividualprogrammingoriginator;sourcedfromtheOriginatorsAPI,responsefield“originatorId”.
programId integer Auniquenumericalidentifierforanindividualprogramname;sourcedfromtheProgramsAPI,responsefield“programId”.
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired(YYYY-MM-DD).originatorId Auniquenumericalidentifierforanindividualprogramming
originator. originatorName Fulloriginatorname.(e.g.“USANETWORK”).programId Auniquenumericalidentifierforanindividualprogramname.changeAction Thetypeofupdate.
• “New”=Addnewprogram• “LineupChange”=Replaceexistingprogram• “Delete”=Deleteexistingprogram
changeDateTime Thetimeatwhichthereprocessingeventoccurred(YYYY-MM-DDHH:MM:SS).
ProgramRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/programRatings
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType DescriptionstartDate(required) string Thefirstdayofthedesiredreporting
period(YYYY-MM-DD).endDate(required) string Thelastdayofthedesiredreportingperiod
(YYYY-MM-DD).demoGroup(required) string Acommaseparatedlistofdemographic
groups(e.g.Females18to49andMales18-24inputasF18-49,M18-24).
originatorId(required) integer Auniquenumericalidentifierforanindividualprogrammingoriginator;sourcedfromtheOriginatorsAPI,responsefield“originatorId”.
daypartId string Auniquecharacteridentifierforanindividualdaypart;sourcedfromtheDaypartsAPI,responsefield“daypartId”.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su
6A-6P)• “CUSTOM”
startTime string Thestarttime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbespecified).
endTime string Theendtime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbespecified).
programId integer Auniquenumericalidentifierforanindividualprogramname;sourcedfromtheProgramsAPI,responsefield“programId”.
summaryTypeCode string Auniquecharacteridentifierforatop-levelgenreclassification;sourcedfromtheGenresAPI,responsefield
“summaryTypeCode”.
dataStreams(required) string Acommaseparatedlistofdatastreams.Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
sample(required) string Thesourcepanelfromwhichtheratingsmetricsareprojected.
• National• Hispanic
ratingMetrics(required) string Acommaseparatedlistofratingmetrics.SpecifiesthemetricsprovidedintheAPIresponse.
• usAaPercentage(TotalU.S.AverageAudiencePercentage=ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
• usAaProjUnits(TotalU.S.AverageAudienceProjection(Units)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute)
• usAaProj000(TotalU.S.AverageAudienceProjection(000)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands)
• usSharePercentage(TotalU.S.SharePercentage=Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecific
program/originator/daypart)
• usHutPutPercentage(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent=ThepercentageofalltelevisionshouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod)
• usHutPutProjUnits(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod)
• usHutPutProj000(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands)
• usAaVpvh0000(ViewersPerViewingHousehold=Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
• cvgAaPercentage(CoverageAreaAverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea)
• cvgSharePercentage(CoverageAreaSharePercent=Thepercentageofhouseholdsorpersonsusing
television(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea)
• cvgHutPutPercentage(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercent=Thepercentageofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
• cvgHutPutProjUnits(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
• cvgHutPutProj000(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)
• usUe000(TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.)
• cvgUe000(TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.)
• usIntab(U.S.Intab=ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
• cvgIntab(CoverageIntab=Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired
(YYYY-MM-DD).telecastReportStartTime Thestarttimeoftheprogramtelecast(HH:MM).calendarDayOfWeekName Thedayoftheweekduringwhichtheprogram
aired(e.g.“THURSDAY”).telecastReportEndTime Theendtimeoftheprogramtelecast(HH:MM).programId Auniquenumericalidentifierforanindividual
programname.episodeId Auniquenumericalidentifierforanindividual
episodeofaprogram.telecastId Auniquenumericalidentifierforanindividual
telecast.originatorId Auniquenumericalidentifierforanindividual
programmingoriginator.originatorType Typeoforiginator
• “Cable”• “Broadcast”• “Syndication”
originatorName Fulloriginatorname.(e.g.“USANETWORK”).programName Fullprogramname.episodeNumber Thesequentialepisodenumberwithinthe
programseries.episodeTitle Thetitleofanindividualprogramepisode.trackageName Auniqueidentifierprovidedbytheclienttotrack
eachtelecast(e.g.“NCISMARATH3P”tracksairingsofNCISthatoccurredonThursdaysat3PM).
summaryTypeCode Auniquecharacteridentifierforthetop-levelgenreclassification(e.g.“GD”=GeneralDrama).
summaryTypeDesc Atop-levelgenreclassification(e.g.“GENERALDRAMA”).
detailedTypeCode Auniquecharacteridentifierforadetailedgenreclassification(e.g.“SD”=Series-Drama).
detailedTypeDesc Adetailedgenreclassification(e.g.“Series-DRAMA).
daypartId Auniquecharacteridentifierforanindividualdaypart.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)
• “WED”(WeekendDaytime-Sa-Su6A-
6P)daypartName Fulldaypartname
• “EARLYFRINGE”• “WEEKDAYMORNING”• “WEEKDAYDAYTIME”• “PRIMETIME”• “LATEFRINGE”• “WEEKENDDAYTIME”
indicators Specialattributesattachedtoprogramsthatletyouselectasetofdaysonwhichselectedprogramsairandalsopermitdroppingofspecials,breakouts,orprogramsoflessthanfiveminutes'duration.Forsyndication,youcanalsodroplong-termprograms.
• (A)=Acquired(AppliedtoanyprogramortelecastthathasairedintheUnitedStatespreviouslyonanothernetwork).
• (B)=Breakout(Appliedatthediscretionofthenetworkatthetelecastleveltoindicateunusualcarriage(e.g.adifferentstarttimeorinterruptedcoverage)).
• (C)=Complex• (D)=Programs<5minutes• (E-A)=EpisodeAcquired• (E-O)=EpisodeOriginal• (G)=Gapped(Appliedforacabletelecast
thatisgapped).• (L)=Live(Appliedatthetelecastlevelon
dualfeednetworkstoindicatethetelecastisairingastheeventoccurs).
• (M)=Movie(Appliedattheprogramlevelforanyprogramdesignatedbytheairingnetworkasamovie).
• (N)=Non-Commercial(Appliedattheprogramortelecastleveltoindicatethatnonationaladsorsponsorshipswereincludedintheprogramortelecast).
• (O)=Original(AppliedtoanyprogramortelecastthathasneverairedintheUnitedStatespreviouslyonanothernetwork).
• (P)=Premiere(Appliedatthetelecastlevelforthefirstepisodestartingamulti-episodeseries).
• (P-A)=ProgramAcquired• (P-O)=ProgramOriginal
• (R)=Repeat(Appliedtoanytelecastthat
hasairedpreviouslyintheUnitedStates).• (S)=Special• (T)=TeamSports(Appliedatthe
programlevelforallprofessionalteamsports).
• (U)=Umbrella• (V)=Various• (X)=UnorderedSustainer• 1=LongTerm
totalDuration Thedurationoftheprogram/telecastairing(minutes).
sample Thesourcepanelfromwhichtheratingsmetricsareprojected.
• “National”• “Hispanic”
dataStream Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
demoGroup ThetargetdemographicprovidedinthedemoGroupparameter.
usAaPercentage TotalU.S.AverageAudiencePercentage(ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
usAaProjUnits TotalU.S.AverageAudienceProjection(Units)(Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute.)
usAaProj000 TotalU.S.AverageAudienceProjection(000)(Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands.)
usSharePercentage TotalU.S.SharePercentage(Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart.)
usHutPutPercentage TotalU.S.HouseholdsUsingTelevision/Persons
UsingTelevisionPercent(ThepercentageofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod.)
usHutPutProjUnits TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod.)
usHutPutProj000 TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands.)
usAaVpvh0000 ViewersPerViewingHousehold(Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
cvgAaPercentage CoverageAreaAverageAudiencePercent(Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea.)
cvgSharePercentage CoverageAreaSharePercent(Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea.)
cvgHutPutPercentage CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercent(Thepercentageofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
cvgHutPutProjUnits CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
cvgHutPutProj000 CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)
usUe000 TheUniverseEstimate(UE)isthetotalnumberof
householdsorpersonswithinthetargetdemographicacrossthetotalU.S.
cvgUe000 TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.
usIntab U.S.Intab(ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
cvgIntab CoverageIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
CommercialRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/commercialRatings
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType DescriptionstartDate(required) string Thefirstdayofthedesiredreporting
period(YYYY-MM-DD).endDate(required) string Thelastdayofthedesiredreportingperiod
(YYYY-MM-DD).demoGroup(required) string Acommaseparatedlistofdemographic
groups(e.g.Females18to49andMales18-24inputasF18-49,M18-24).
originatorId(required) integer Auniquenumericalidentifierforanindividualprogrammingoriginator;sourcedfromtheOriginatorsAPI,responsefield“originatorId”.
daypartId string Auniquecharacteridentifierforanindividualdaypart;sourcedfromtheDaypartsAPI,responsefield“daypartId”.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su
6A-6P)• “CUSTOM”
startTime string Thestarttime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbespecified).
endTime string Theendtime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbespecified).
programId integer Auniquenumericalidentifierforanindividualprogramname;sourcedfromtheProgramsAPI,responsefield“programId”.
summaryTypeCode string Auniquecharacteridentifierforatop-levelgenreclassification;sourcedfromtheGenresAPI,responsefield“summaryTypeCode”.
dataStreams(required) string Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
sample(required) string Thesourcepanelfromwhichtheratingsmetricsareprojected.
• National• Hispanic
ratingMetrics(required) string Acommaseparatedlistofratingmetrics.SpecifiesthemetricsprovidedintheAPIresponse.
• nccmUsAaPercentage(NationalCommercialClockMinuteAverageAudiencePercentage=ThepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)
• nccmUsAaProjUnits(NationalCommercialClockMinuteAverageAudienceProjection(Units)=TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)
• nccmUsAaProj000(NationalCommercialClockMinuteAverage
AudienceProjection(000)=TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.,expressedinthousands)
• nccmCvgAaPercentage(NationalCommercialClockMinuteCoverageAreaAverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteofaselectedprogramwithinanetwork’scoveragearea)
• usUe000(TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.)
• cvgUe000(TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.)
• usIntab(U.S.Intab=ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
• cvgIntab(CoverageIntab=Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired
(YYYY-MM-DD).telecastReportStartTime Thestarttimeoftheprogramtelecast(HH:MM).calendarDayOfWeekName Thedayoftheweekduringwhichtheprogram
aired(e.g.“THURSDAY”).telecastReportEndTime Theendtimeoftheprogramtelecast(HH:MM).programId Auniquenumericalidentifierforanindividual
programname.episodeId Auniquenumericalidentifierforanindividual
episodeofaprogram.
telecastId Auniquenumericalidentifierforanindividualtelecast.
originatorId Auniquenumericalidentifierforanindividualprogrammingoriginator.
originatorType Typeoforiginator• “Cable”• “Broadcast”• “Syndication”
originatorName Fulloriginatorname.(e.g.“USANETWORK”).programName Fullprogramname.episodeNumber Thesequentialepisodenumberwithinthe
programseries.episodeTitle Thetitleofanindividualprogramepisode.trackageName Auniqueidentifierprovidedbytheclienttotrack
eachtelecast(e.g.“NCISMARATH3P”tracksairingsofNCISthatoccurredonThursdaysat3PM).
summaryTypeCode Auniquecharacteridentifierforthetop-levelgenreclassification(e.g.“GD”=GeneralDrama).
summaryTypeDesc Atop-levelgenreclassification(e.g.“GENERALDRAMA”).
detailedTypeCode Auniquecharacteridentifierforadetailedgenreclassification(e.g.“SD”=Series-Drama).
detailedTypeDesc Adetailedgenreclassification(e.g.“Series-DRAMA).
daypartId Auniquecharacteridentifierforanindividualdaypart.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su6A-
6P)daypartName Fulldaypartname
• “EARLYFRINGE”• “WEEKDAYMORNING”• “WEEKDAYDAYTIME”• “PRIMETIME”• “LATEFRINGE”• “WEEKENDDAYTIME”
indicators Specialattributesattachedtoprogramsthatlet
youselectasetofdaysonwhichselectedprogramsairandalsopermitdroppingofspecials,breakouts,orprogramsoflessthanfiveminutes'duration.Forsyndication,youcanalsodroplong-termprograms.
• (A)=Acquired(AppliedtoanyprogramortelecastthathasairedintheUnitedStatespreviouslyonanothernetwork).
• (B)=Breakout(Appliedatthediscretionofthenetworkatthetelecastleveltoindicateunusualcarriage(e.g.adifferentstarttimeorinterruptedcoverage)).
• (C)=Complex• (D)=Programs<5minutes• (E-A)=EpisodeAcquired• (E-O)=EpisodeOriginal• (G)=Gapped(Appliedforacabletelecast
thatisgapped).• (L)=Live(Appliedatthetelecastlevelon
dualfeednetworkstoindicatethetelecastisairingastheeventoccurs).
• (M)=Movie(Appliedattheprogramlevelforanyprogramdesignatedbytheairingnetworkasamovie).
• (N)=Non-Commercial(Appliedattheprogramortelecastleveltoindicatethatnonationaladsorsponsorshipswereincludedintheprogramortelecast).
• (O)=Original(AppliedtoanyprogramortelecastthathasneverairedintheUnitedStatespreviouslyonanothernetwork).
• (P)=Premiere(Appliedatthetelecastlevelforthefirstepisodestartingamulti-episodeseries).
• (P-A)=ProgramAcquired• (P-O)=ProgramOriginal• (R)=Repeat(Appliedtoanytelecastthat
hasairedpreviouslyintheUnitedStates).• (S)=Special• (T)=TeamSports(Appliedatthe
programlevelforallprofessionalteamsports).
• (U)=Umbrella• (V)=Various• (X)=UnorderedSustainer
• 1=LongTerm
totalDuration Thedurationoftheprogram/telecastairing(minutes).
sample Thesourcepanelfromwhichtheratingsmetricsareprojected.
• “National”• “Hispanic”
dataStream Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
demoGroup ThetargetdemographicprovidedinthedemoGroupparameter.
nccmUsAaPercentage NationalCommercialClockMinuteAverageAudiencePercentage(ThepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)
nccmUsAaProjUnits NationalCommercialClockMinuteAverageAudienceProjection(Units)(TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)
nccmUsAaProj000 NationalCommercialClockMinuteAverageAudienceProjection(000)(TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.,expressedinthousands.)
nccmCvgAaPercentage NationalCommercialClockMinuteCoverageAreaAverageAudiencePercent(Thepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteofaselectedprogramwithinanetwork’scoveragearea.)
usUe000 TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.
cvgUe000 TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.
usIntab U.S.Intab(ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
cvgIntab CoverageIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthe
televisionpanelacrossthenetwork’scoveragearea.)
nccmDuration NationalCommericalClockMinutesDuration(seconds)(Thetotalnumberofsecondsacrossqualifiedcommercialminuteswithinaselectedprogram.)
QuarterHourProgramRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/quarterHourRatings
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType DescriptionstartDate(required) string Thefirstdayofthedesiredreporting
period(YYYY-MM-DD).endDate(required) string Thelastdayofthedesiredreportingperiod
(YYYY-MM-DD).demoGroup(required) string Acommaseparatedlistofdemographic
groups(e.g.Females18to49andMales18-24inputasF18-49,M18-24).
originatorId(required) integer Auniquenumericalidentifierforanindividualprogrammingoriginator;sourcedfromtheOriginatorsAPI,responsefield“originatorId”.
daypartId(required) string Auniquecharacteridentifierforanindividualdaypart;sourcedfromtheDaypartsAPI,responsefield“daypartId”.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su
6A-6P)• “CUSTOM”
startTime string Thestarttime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbe
specified).
endTime string Theendtime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbespecified).
programId integer Auniquenumericalidentifierforanindividualprogramname;sourcedfromtheProgramsAPI,responsefield“programId”.
summaryTypeCode string Auniquecharacteridentifierforatop-levelgenreclassification;sourcedfromtheGenresAPI,responsefield“summaryTypeCode”.
dataStreams(required) string Acommaseparatedlistofdatastreams.Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
sample(required) string Thesourcepanelfromwhichtheratingsmetricsareprojected.
• National• Hispanic
ratingMetrics(required) string Acommaseparatedlistofratingmetrics.SpecifiesthemetricsprovidedintheAPIresponse.
• usAaPercentage(TotalU.S.AverageAudiencePercentage=ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
• usAaProjUnits(TotalU.S.AverageAudienceProjection(Units)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute)
• usAaProj000(TotalU.S.AverageAudienceProjection(000)=The
projectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands)
• usSharePercentage(TotalU.S.SharePercentage=Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart)
• usHutPutPercentage(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent=ThepercentageofalltelevisionshouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod)
• usHutPutProjUnits(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod)
• usHutPutProj000(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands)
• usAaVpvh0000(ViewersPerViewingHousehold=Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
• cvgAaPercentage(CoverageArea
AverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea)
• cvgSharePercentage(CoverageAreaSharePercent=Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea)
• cvgHutPutPercentage(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercent=Thepercentageofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
• cvgHutPutProjUnits(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
• cvgHutPutProj000(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)
• usUe000(TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.)
• cvgUe000(TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.)
• usIntab(U.S.Intab=Thenumberofhouseholdsorpersonssupplying
usableinformationwithinthetelevisionpanelacrossthetotalU.S.)
• cvgIntab(CoverageIntab=Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired
(YYYY-MM-DD).telecastReportStartTime Thestarttimeoftheprogramtelecast(HH:MM).calendarDayOfWeekName Thedayoftheweekduringwhichtheprogram
aired(e.g.“THURSDAY”).telecastReportEndTime Theendtimeoftheprogramtelecast(HH:MM).programId Auniquenumericalidentifierforanindividual
programname.episodeId Auniquenumericalidentifierforanindividual
episodeofaprogram.telecastId Auniquenumericalidentifierforanindividual
telecast.originatorId Auniquenumericalidentifierforanindividual
programmingoriginator.originatorType Typeoforiginator
• “Cable”• “Broadcast”• “Syndication”
originatorName Fulloriginatorname.(e.g.“USANETWORK”).programName Fullprogramname.episodeNumber Thesequentialepisodenumberwithinthe
programseries.episodeTitle Thetitleofanindividualprogramepisode.trackageName Auniqueidentifierprovidedbytheclienttotrack
eachtelecast(e.g.“NCISMARATH3P”tracksairingsofNCISthatoccurredonThursdaysat3PM).
summaryTypeCode Auniquecharacteridentifierforthetop-levelgenreclassification(e.g.“GD”=GeneralDrama).
summaryTypeDesc Atop-levelgenreclassification(e.g.“GENERALDRAMA”).
detailedTypeCode Auniquecharacteridentifierforadetailedgenreclassification(e.g.“SD”=Series-Drama).
detailedTypeDesc Adetailedgenreclassification(e.g.“Series-DRAMA).
daypartId Auniquecharacteridentifierforanindividual
daypart.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su6A-
6P)daypartName Fulldaypartname
• “EARLYFRINGE”• “WEEKDAYMORNING”• “WEEKDAYDAYTIME”• “PRIMETIME”• “LATEFRINGE”• “WEEKENDDAYTIME”
indicators Specialattributesattachedtoprogramsthatletyouselectasetofdaysonwhichselectedprogramsairandalsopermitdroppingofspecials,breakouts,orprogramsoflessthanfiveminutes'duration.Forsyndication,youcanalsodroplong-termprograms.
• (A)=Acquired(AppliedtoanyprogramortelecastthathasairedintheUnitedStatespreviouslyonanothernetwork).
• (B)=Breakout(Appliedatthediscretionofthenetworkatthetelecastleveltoindicateunusualcarriage(e.g.adifferentstarttimeorinterruptedcoverage)).
• (C)=Complex• (D)=Programs<5minutes• (E-A)=EpisodeAcquired• (E-O)=EpisodeOriginal• (G)=Gapped(Appliedforacabletelecast
thatisgapped).• (L)=Live(Appliedatthetelecastlevelon
dualfeednetworkstoindicatethetelecastisairingastheeventoccurs).
• (M)=Movie(Appliedattheprogramlevelforanyprogramdesignatedbytheairingnetworkasamovie).
• (N)=Non-Commercial(Appliedattheprogramortelecastleveltoindicatethatnonationaladsorsponsorshipswere
includedintheprogramortelecast).
• (O)=Original(AppliedtoanyprogramortelecastthathasneverairedintheUnitedStatespreviouslyonanothernetwork).
• (P)=Premiere(Appliedatthetelecastlevelforthefirstepisodestartingamulti-episodeseries).
• (P-A)=ProgramAcquired• (P-O)=ProgramOriginal• (R)=Repeat(Appliedtoanytelecastthat
hasairedpreviouslyintheUnitedStates).• (S)=Special• (T)=TeamSports(Appliedatthe
programlevelforallprofessionalteamsports).
• (U)=Umbrella• (V)=Various• (X)=UnorderedSustainer• 1=LongTerm
totalDuration Thedurationoftheprogram/telecastairing(minutes).
sample Thesourcepanelfromwhichtheratingsmetricsareprojected.
• “National”• “Hispanic”
intervalOfBroadcastDayId Anumericalidentifierforthesequentialquarterhourofthebroadcastday(e.g.52=intervalof18:00-18:15basedonthe06:00-06:00broadcastday).
intervalStartTime Thestartminuteofthetelecastwithinthequarterhourinterval.
intervalEndTime Theendminuteofthetelecastwithinthequarterhourinterval.
intervalDuration Thedurationofthetelecastwithinthequarterhourinterval.
dataStream Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesall
playbackthatoccurredwithinsevendaysoftheliveairing).
demoGroup ThetargetdemographicprovidedinthedemoGroupparameter.
usAaPercentage TotalU.S.AverageAudiencePercentage(ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
usAaProjUnits TotalU.S.AverageAudienceProjection(Units)(Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute.)
usAaProj000 TotalU.S.AverageAudienceProjection(000)(Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands.)
usSharePercentage TotalU.S.SharePercentage(Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart.)
usHutPutPercentage TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent(ThepercentageofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod.)
usHutPutProjUnits TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod.)
usHutPutProj000 TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands.)
usAaVpvh0000 ViewersPerViewingHousehold(Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
cvgAaPercentage CoverageAreaAverageAudiencePercent(Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea.)
cvgSharePercentage CoverageAreaSharePercent(Thepercentageof
householdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea.)
cvgHutPutPercentage CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercent(Thepercentageofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
cvgHutPutProjUnits CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
cvgHutPutProj000 CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)
usUe000 TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.
cvgUe000 TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.
usIntab U.S.Intab(ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
cvgIntab CoverageIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
TimePeriodRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/timePeriodRatings
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType DescriptionstartDate(required) string Thefirstdayofthedesiredreporting
period(YYYY-MM-DD).
endDate(required) string Thelastdayofthedesiredreportingperiod
(YYYY-MM-DD).demoGroup(required) string Acommaseparatedlistofdemographic
groups(e.g.Females18to49andMales18-24inputasF18-49,M18-24).
viewingSourceId(required) integer Auniquenumericalidentifierforanindividualviewingsource;sourcedfromtheViewingSourcesAPI,responsefield“viewingSourceId”.
daypartIds string Acommaseparatedlistofcharacteridentifiersfordayparts;sourcedfromtheDaypartsAPI,responsefield“daypartId”.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)• “WED”(WeekendDaytime-Sa-Su
6A-6P)• “CUSTOM”
timePeriods string Acommaseparatedlistofstarttimeandendtimevaluesforcustomtimeperiods(e.g.06:00-06:59,13:00-14:29)
dataStreams(required) string Acommaseparatedlistofdatastreams.Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
sample(required) string Thesourcepanelfromwhichtheratingsmetricsareprojected.
• National• Hispanic
ratingMetrics(required) string Acommaseparatedlistofratingmetrics.
SpecifiesthemetricsprovidedintheAPIresponse.
• usAaPercentage(TotalU.S.AverageAudiencePercentage=ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
• usAaProjUnits(TotalU.S.AverageAudienceProjection(Units)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute)
• usAaProj000(TotalU.S.AverageAudienceProjection(000)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands)
• usSharePercentage(TotalU.S.SharePercentage=Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart)
• usHutPutPercentage(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent=ThepercentageofalltelevisionshouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod)
• usHutPutProjUnits(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod)
• usHutPutProj000(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevision
Projection(000)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands)
• usAaVpvh0000(ViewersPerViewingHousehold=Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
• cvgAaPercentage(CoverageAreaAverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea)
• cvgSharePercentage(CoverageAreaSharePercent=Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea)
• cvgHutPutPercentage(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercent=Thepercentageofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
• cvgHutPutProjUnits(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
• cvgHutPutProj000(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevision
Projection(000)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)
• usUe000(TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.)
• cvgUe000(TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.)
• usIntab(U.S.Intab=ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
• cvgIntab(CoverageIntab=Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
ResponseField DescriptionviewingSourceId Auniquenumericalidentifierforanindividual
viewingsource.viewingSourceName Fullviewingsourcename(e.g.“HOMEAND
GARDENTV”).sample Thesourcepanelfromwhichtheratingsmetrics
areprojected.• “National”• “Hispanic”
daypartId Auniquecharacteridentifierforanindividualdaypart.
• “EF”(EarlyFringe-M-Sa6P-8P,Su6P-7P)
• “WKM”(WeekdayMorning-M-F6A-10A)
• “WKD”(WeekdayDaytime-M-F10A-6P)
• “PRI”(PrimeTime-M-Sa8P-11P,Su7P-11P)
• “LF”(LateFringe-M-Su11P-6A)
• “WED”(WeekendDaytime-Sa-Su6A-
6P)daypartName Fulldaypartname
• “EARLYFRINGE”• “WEEKDAYMORNING”• “WEEKDAYDAYTIME”• “PRIMETIME”• “LATEFRINGE”• “WEEKENDDAYTIME”
startTime Thestarttimeofatimeperiod(HH:MM:SS)endTime Theendtimeofatimeperiod(HH:MM:SS) dataStream Time-shiftedviewingfromDVRPlaybackorOn-
demandcontentwiththesamecommercialload.• “Live”(Live-Includesviewingthat
occurredduringtheliveairing).• “Live+SD”(Live+SameDay-Includesall
playbackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
demoGroup ThetargetdemographicprovidedinthedemoGroupparameter.
usAaPercentage TotalU.S.AverageAudiencePercentage(ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
usAaProjUnits TotalU.S.AverageAudienceProjection(Units)(Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute.)
usAaProj000 TotalU.S.AverageAudienceProjection(000)(Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands.)
usSharePercentage TotalU.S.SharePercentage(Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart.)
usHutPutPercentage TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent(ThepercentageofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteof
aspecifictimeperiod.)
usHutPutProjUnits TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod.)
usHutPutProj000 TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands.)
usAaVpvh0000 ViewersPerViewingHousehold(Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
cvgAaPercentage CoverageAreaAverageAudiencePercent(Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea.)
cvgSharePercentage CoverageAreaSharePercent(Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea.)
cvgHutPutPercentage CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercent(Thepercentageofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
cvgHutPutProjUnits CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea.)
cvgHutPutProj000 CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)
usUe000 TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.
cvgUe000 TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthe
targetdemographicacrossthenetwork’scoveragearea.
usIntab U.S.Intab(ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
cvgIntab CoverageIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
SubmitBatchRequestAPIPOSTRequestURL:https://api.developer.nielsen.com/watchapi/batch/national/submit-batch-request
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
body(required) string JSONlistofrequests.{“requests”:[(“url”:<RequestURL>,“params”:<parameters>,”method”:GET},{[(“url”:<RequestURL>,“params”:<parameters>,”method”:GET}]}
ResponseField DescriptionbatchId Auniquenumericalidentifierforabatchrequest.id Auniquenumericalidentifierforarequestwithinabatch. method Themethod(e.g.GET)forarequestwithinabatch.url TherequestURLforarequestwithinabatch.params Theparametersofarequestwithinabatch.
GetBatchStatusAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/batch/national/get-batch-status
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName Parameter Description
Type
batchId(required) string Auniquenumericalidentifierforabatchrequest;sourcedfromtheSubmitBatchRequestAPI.
ResponseField DescriptionbatchId Auniquenumericalidentifierforabatchrequest.status Thestatusofasubmittedbatchrequest.
• Queued• Processing• Completed• Failed
GetBatchResponseAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/batch/national/get-batch-response
Pleasenote,theresponsebodyisazippedJSONfilethatmustbesavedtotheclientmachine.
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
batchId(required) string Auniquenumericalidentifierforabatchrequest;sourcedfromtheSubmitBatchRequestAPI.
ResponseField DescriptionbatchId Auniquenumericalidentifierforabatchrequest.status Thestatusofasubmittedbatchrequest.
• Completed• Failed
body JSONresponsecontenttransferredasaZipfile.