Nielsen Audience API v1.3 Technical Reference Audience API Technical Reference ... string The last...
Transcript of Nielsen Audience API v1.3 Technical Reference Audience API Technical Reference ... string The last...
NielsenAudienceAPITechnicalReference
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/analytics/api/v1/dataAvailability
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ResponseField DescriptiondataType Adescriptionofthetypeofdatareported.
• “BroadcastPrime”• “BroadcastTotalDay”• “CableTotalDay”• “SyndicationTotalDay”• “MobileCensus”• “PCCensus”• “BroadcastAdvertisement”• “CableAdvertisement”• “SyndicationAdvertisement”
originatorType Typeoforiginator.
• “Broadcast”• “Cable”• “Syndication”• “Digital”
dataStream Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
• “Live+14”(Live+14Days–Includesallplaybackthatoccurredwithinfourteendaysoftheliveairing).
• “Live+21”(Live+21Days–Includesallplaybackthatoccurredwithintwentyonedaysoftheliveairing).
• “Live+28”(Live+28Days–Includesallplaybackthatoccurredwithintwentyeightdaysoftheliveairing).
• “Live+35”(Live+35Days–Includesallplaybackthatoccurredwithinthirtyfivedaysoftheliveairing).
releaseType Thetypeofdatarelease.• “Prelim”–PreliminaryData• “Final”–FinalData
earliestAvailability Theearliestreportabledate(YYYY-MM-DD).latestAvailability Themostrecentreportabledate(YYYY-MM-DD).
OriginatorsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/originators
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
originatorType string Typeoforiginator.• “Cable”• “Broadcast”• “Syndication”
sample(required) string Thesourcepanelfromwhichviewingis
collected.
• “National”• “Hispanic”
startDate(required) string Thefirstdayofthemeasurementinterval(YYYY-MM-DD).
endDate(required) string Thelastdayofthemeasurementinterval(YYYY-MM-DD).
ResponseField Descriptionoriginator Abbreviatedoriginatorname(e.g.“ABC”).Thisfieldisusedasan
inputtotheoriginatorsfieldintheRatingsAPIs. originatorType Typeoforiginator.
• “Cable”• “Broadcast”• “Syndication”
originatorName Thefulloriginatorname.
MarketBreaksAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/marketBreaks
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
sample(required) string Thesourcepanelfromwhichviewingiscollected.
• “National”• “Hispanic”
ResponseField DescriptionmarketBreakId Auniquenumericalidentifierforamarketbreak.Thisvalueis
passedintothe“marketBreaks”inputparameteroftheratingsAPIrequests.
marketBreak Anaudiencesegmentbasedonhouseholdcharacteristics(e.g.HouseholdIncome125K+,HouseholdSize2,etc.)
marketSection Acategoryofaudiencesegmentsbasedonhouseholdcharacteristics.
DemographicsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/demographics
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ResponseField Descriptiondemographic Thenameofthedemographic.Thisvalue,alongwithanage
range,ispassedinthe“demographics”inputparameteroftheratingsAPIrequests.
demographicSection Thecategoryofthedemographic.
ReprocessingNotificationsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/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).
originatorType string Typeoforiginator.• “Cable”• “Broadcast”• “Syndication”
originator string Abbreviatedoriginatorname;sourcedfromtheOriginatorsAPI.
programId integer Auniquenumericalidentifierforaprogram.
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired(YYYY-MM-DD).originator Abbreviatedoriginatorname(e.g.“ABC”).Thisfieldisusedasan
inputtotheoriginatorsfieldintheRatingsAPIs.
programId Auniquenumericalidentifierfortheprogramthathasbeen
reprocessed.programName Thenameoftheprogramthathasbeenreprocessed.telecastId Auniquenumericalidentifierforthetelecastthathasbeen
reprocessed.telecastStartTime Thestarttimeofthetelecastthathasbeenreprocessed.changeAction Thereprocessingaction.
• “LabelChange”• “LineupChange”• “Delete”
changeDateTime Thedateandtimeofthereprocessing.changeType Thetypeofreprocessing.
• “Program”• “Commercial”
ProgramRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/programRatings
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
sample(required) string Thesourcepanelfromwhichviewingiscollected.
• National• Hispanic
startDate(required) string Thefirstdayofthemeasurementinterval(YYYY-MM-DD).Maximumof7dayspriortoenddate.
endDate(required) string Thelastdayofthemeasurementinterval(YYYY-MM-DD).Maximumof7daysafterstartdate.
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)startTime string Thestarttime(HH:MM)ofthedaypart.Earliest
timeis06:00;latesttimeis05:59.endTime string Theendtime(HH:MM)ofthedaypart.Earliest
timeis06:00;latesttimeis05:59.marketBreaks string Acommaseparatedlistofmarketbreaks
formattedasastring.TheinputvaluesshouldmarketbreakIDintegers,sourcedfromtheMarketBreaksAPI.Forexample:
• “0”(TotalComposite)• “94”(HispanicOrigin)• “0,94”(ReturnsratingsforbothTotal
CompositeandHispanicOrigin)Booleanexpressionscanalsobespecifiedformarketbreaks,includingAND,OR,NOToperators.Forexample:
• “52AND53”• “52AND53,(27AND29)OR36”
Note:Bydefault,theAPIwillreturntototalcompositemarketbreaksforeachsampletype.ForNationalsample,thatismarketbreak0(TotalComposite).ForHispanicsample,thatismarketbreak94(HispanicOrigin).
demographics(required) string Acommaseparatedlistofdemographicsformattedasastring.Theinputvaluesshouldincludedemographicvaluesandageranges.Forexample:
• “Household”• “Persons18-49”• “Males35-54”• “Females55-999”• “Full-timeWorkingWomen18-54”
Maximumof38demographicsperrequest.
originators(required) string Originator,sourcedfromtheOriginatorsAPI.dataStreams(required) string Acommaseparatedlistofdatastreams.
Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesall
playbackthatoccurredwithinthesamedayoftheliveairing).
• “Live+1”(Live+1Day–Includesallplaybackthatoccurredwithinonedayoftheliveairing).
• “Live+2”(Live+2Days–Includesallpalybackthatoccurredwithintwodaysoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+4”(Live+4Days–Includesallplaybackthatoccurredwithinfourdaysoftheliveairing).
• “Live+5”(Live+5Days–Includesallplaybackthatoccurredwithinfivedaysoftheliveairing).
• “Live+6”(Live+6Days–Includesallplaybackthatoccurredwithsixdaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
• “Live+8”(Live+8Days-Includesallplaybackthatoccurredwithineightdaysoftheliveairing).
• “Live+9”(Live+9Days–Includesallplaybackthatoccurredwithinninedaysoftheliveairing).
• “Live+10”(Live+10Days–Includesallplaybackthatoccurredwithintendaysoftheliveairing).
• “Live+11”(Live+11Days–Includesallplaybackthatoccurredwithelevendaysoftheliveairing).
• “Live+12”(Live+12Days-Includesallplaybackthatoccurredwithintwelvedaysoftheliveairing).
• “Live+13”(Live+13Days-Includesallplaybackthatoccurredwithinthirteendaysoftheliveairing).
• “Live+14”(Live+14Days–Includesallplaybackthatoccurredwithinfourteendaysoftheliveairing).
• “Live+15”(Live+15Days–Includesallplaybackthatoccurredwithinfifteendaysoftheliveairing).
• “Live+16”(Live+16Days–Includesall
playbackthatoccurredwithsixteendaysoftheliveairing).
• “Live+17”(Live+17Days-Includesallplaybackthatoccurredwithinseventeendaysoftheliveairing).
• “Live+18”(Live+18Days-Includesallplaybackthatoccurredwithineighteendaysoftheliveairing).
• “Live+19”(Live+19Days–Includesallplaybackthatoccurredwithinnineteendaysoftheliveairing).
• “Live+20”(Live+20Days–Includesallplaybackthatoccurredwithintwentydaysoftheliveairing).
• “Live+21”(Live+21Days–Includesallplaybackthatoccurredwithtwentyonedaysoftheliveairing).
• “Live+22”(Live+22Days-Includesallplaybackthatoccurredwithintwentytwodaysoftheliveairing).
• “Live+23”(Live+23Days-Includesallplaybackthatoccurredwithintwentythreedaysoftheliveairing).
• “Live+24”(Live+24Days–Includesallplaybackthatoccurredwithintwentyfourdaysoftheliveairing).
• “Live+25”(Live+25Days–Includesallplaybackthatoccurredwithintwentyfivedaysoftheliveairing).
• “Live+26”(Live+26Days–Includesallplaybackthatoccurredwithtwentysixdaysoftheliveairing).
• “Live+27”(Live+27Days-Includesallplaybackthatoccurredwithintwentysevendaysoftheliveairing).
• “Live+28”(Live+28Days-Includesallplaybackthatoccurredwithintwentyeightdaysoftheliveairing).
• “Live+29”(Live+29Days–Includesallplaybackthatoccurredwithintwentyninedaysoftheliveairing).
• “Live+30”(Live+30Days–Includesallplaybackthatoccurredwithinthirtydaysoftheliveairing).
• “Live+31”(Live+31Days–Includesallplaybackthatoccurredwiththirtyone
daysoftheliveairing).
• “Live+32”(Live+32Days-Includesallplaybackthatoccurredwithinthirtytwodaysoftheliveairing).
• “Live+33”(Live+33Days-Includesallplaybackthatoccurredwithinthirtythreedaysoftheliveairing).
• “Live+34”(Live+34Days–Includesallplaybackthatoccurredwithinthirtyfourdaysoftheliveairing).
• “Live+35”(Live+35Days–Includesallplaybackthatoccurredwithinthirtyfivedaysoftheliveairing).
Maximumof8datastreamsperrequest.
mediaSources(required) string Thecontributingplatformforviewing.• TVWithDigital• TV• Digital• Computer• Mobile• Tablet• Smartphone• PortableMediaPlayer• Others
contribution(required) string ThecontributingviewingfromVODwiththesameadloadaslineartelecast.
• LinearWithVOD• Linear• VOD
ratingMetrics string Acommaseparatedlistofratingmetrics.Nospecificationwillreturnallmetrics.
• usAaPercentage(TotalU.S.AverageAudiencePercentage=ThepercentageofthetargetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.S.)
• usAaProjUnits(TotalU.S.AverageAudienceProjection(Units)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute)
• usAaProj000(TotalU.S.AverageAudienceProjection(000)=Theprojectednumberofhouseholdstunedorpersonsviewinga
program/originator/daypartduringtheaverageminute,expressedinthousands)
• usSharePercentage(TotalU.S.SharePercentage=Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart.)
• usHutPutPercentage(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercentage=ThepercentageofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecificprogramortimeperiod.)
• usHutPutProjUnits(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecificprogramortimeperiod.)
• usHutPutProj000(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=TheprojectedestimateofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecificprogramortimeperiod,expressedinthousands)
• usAaVpvh0000(ViewersPerViewingHousehold=Theprojectednumberofviewersper10,000projectedhouseholdspassingpersoneditsfortheaverageminutesofaselectedprogramortimeperiod.Inotherwords,itisthenumberofviewingpersonspertuninghousehold.)
• cvgAaPercentage(CoverageAreaAverageAudiencePercentage=Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea.)
• weightedViewingMinutes(Weighted
ViewingMinutes=Theestimatedtotalnumberofviewingminutesfortheprojectedaudienceofaspecificprogramortimeperiod.)
• cvgSharePercentage(CoverageAreaSharePercentage=Thepercentageofcoverageareahouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart.)
• cvgHutPutPercentage(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercentage=Thepercentageofalltelevisionhouseholdswithinthecoverageareausingtheirtelevisionsetsduringtheaverageminuteofaspecifiedprogramortimeperiod.)
• cvgHutPutProjUnits(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)=Theprojectedestimateofalltelevisionhouseholdswithinthecoverageareausingtheirtelevisionsetsduringtheaverageminuteofaspecifiedprogramortimeperiod.)
• cvgHutPutProj000(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=Theprojectedestimateofalltelevisionhouseholdswithinthecoverageareausingtheirtelevisionsetsduringtheaverageminuteofaspecifiedprogramortimeperiod,expressedinthousands.)
• usUe000(TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.)
• cvgUe000(TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.)
• usIntab(U.S.Intab=ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
• cvgIntab(CoverageAreaIntab=The
numberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
Allratingmetricswillbereturnedifthisparameterisnotspecifiedintherequest.
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired(YYYY-MM-DD).sample Thesourcepanelfromwhichviewingiscollected.
• “National”• “Hispanic”
programId Auniquenumericalidentifierforanindividualprogramname.telecastId Auniquenumericalidentifierforanindividualtelecast.originator Abbreviatedoriginatorname.(e.g.“ABC”).trackageId Auniquenumericalidentifierprovidedbythenetworktotrack
eachtelecast.trackageName Auniqueidentifierprovidedbythenetworktotrackeachtelecast
(e.g.“NCISMARATH3P”tracksairingsofNCISthatoccurredonThursdaysat3PM).
summaryTypeCode Auniquecharacteridentifierforthetop-levelgenreclassification(e.g.“GD”=GeneralDrama).
detailedTypeCode Auniquecharacteridentifierforadetailedgenreclassification(e.g.“SD”=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)
reportedDuration Thedurationofthetelecastairing(minutes).telecastReportStartTime Thestarttimeofthetelecast(HH:MM).calendarDayOfWeekName Thedayoftheweekduringwhichtheprogramaired(e.g.
“THURSDAY”).telecastReportEndTime Theendtimeofthetelecast(HH:MM).originatorType Typeoforiginator
• “Cable”• “Broadcast”• “Syndication”
programName Thefullprogramname.episodeName Atitleforanindividualepisodeofaprogram.feedPattern Thepatternofdeliveryforthetelecast.
• “B”–Broadcast
• “L”–Live• “D”-Dual
specialIndicator • “S”–SpecialProgrambreakoutIndicator • “B”–BreakoutpremiereIndicator • “P”-PremiererepeatIndicator • “R”-RepeatgappedIndicator • “G”-GappedsustainerIndicator • “S”-SustainerliveIndicator • “L”–Liveairingcontribution ThecontributingviewingfromVODwiththesameadloadaslinear
telecast.• LinearWithVOD• Linear• VOD
mediaSource Thecontributingplatformforviewing.• TVwithDigital• TV• Digital• Computer• Mobile• Tablet• Smartphone• PortableMediaPlayer• Others
dataStream Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+1”(Live+1Day–Includesallplaybackthatoccurredwithinonedayoftheliveairing).
• “Live+2”(Live+2Days–Includesallpalybackthatoccurredwithintwodaysoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+4”(Live+4Days–Includesallplaybackthatoccurredwithinfourdaysoftheliveairing).
• “Live+5”(Live+5Days–Includesallplaybackthatoccurredwithinfivedaysoftheliveairing).
• “Live+6”(Live+6Days–Includesallplaybackthatoccurredwithsixdaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
• “Live+8”(Live+8Days-Includesallplaybackthatoccurredwithineightdaysoftheliveairing).
• “Live+9”(Live+9Days–Includesallplaybackthat
occurredwithinninedaysoftheliveairing).• “Live+10”(Live+10Days–Includesallplaybackthat
occurredwithintendaysoftheliveairing).• “Live+11”(Live+11Days–Includesallplaybackthat
occurredwithelevendaysoftheliveairing).• “Live+12”(Live+12Days-Includesallplaybackthat
occurredwithintwelvedaysoftheliveairing).• “Live+13”(Live+13Days-Includesallplaybackthat
occurredwithinthirteendaysoftheliveairing).• “Live+14”(Live+14Days–Includesallplaybackthat
occurredwithinfourteendaysoftheliveairing).• “Live+15”(Live+15Days–Includesallplaybackthat
occurredwithinfifteendaysoftheliveairing).• “Live+16”(Live+16Days–Includesallplaybackthat
occurredwithsixteendaysoftheliveairing).• “Live+17”(Live+17Days-Includesallplaybackthat
occurredwithinseventeendaysoftheliveairing).• “Live+18”(Live+18Days-Includesallplaybackthat
occurredwithineighteendaysoftheliveairing).• “Live+19”(Live+19Days–Includesallplaybackthat
occurredwithinnineteendaysoftheliveairing).• “Live+20”(Live+20Days–Includesallplaybackthat
occurredwithintwentydaysoftheliveairing).• “Live+21”(Live+21Days–Includesallplaybackthat
occurredwithtwentyonedaysoftheliveairing).• “Live+22”(Live+22Days-Includesallplaybackthat
occurredwithintwentytwodaysoftheliveairing).• “Live+23”(Live+23Days-Includesallplaybackthat
occurredwithintwentythreedaysoftheliveairing).• “Live+24”(Live+24Days–Includesallplaybackthat
occurredwithintwentyfourdaysoftheliveairing).• “Live+25”(Live+25Days–Includesallplaybackthat
occurredwithintwentyfivedaysoftheliveairing).• “Live+26”(Live+26Days–Includesallplaybackthat
occurredwithtwentysixdaysoftheliveairing).• “Live+27”(Live+27Days-Includesallplaybackthat
occurredwithintwentysevendaysoftheliveairing).• “Live+28”(Live+28Days-Includesallplaybackthat
occurredwithintwentyeightdaysoftheliveairing).• “Live+29”(Live+29Days–Includesallplaybackthat
occurredwithintwentyninedaysoftheliveairing).• “Live+30”(Live+30Days–Includesallplaybackthat
occurredwithinthirtydaysoftheliveairing).• “Live+31”(Live+31Days–Includesallplaybackthat
occurredwiththirtyonedaysoftheliveairing).• “Live+32”(Live+32Days-Includesallplaybackthat
occurredwithinthirtytwodaysoftheliveairing).
• “Live+33”(Live+33Days-Includesallplaybackthatoccurredwithinthirtythreedaysoftheliveairing).
• “Live+34”(Live+34Days–Includesallplaybackthatoccurredwithinthirtyfourdaysoftheliveairing).
• “Live+35”(Live+35Days–Includesallplaybackthatoccurredwithinthirtyfivedaysoftheliveairing).
marketBreakId AuniquenumericalidentifierforaMarketBreak.marketBreak Anaudiencesegmentbasedonhouseholdcharacteristics(e.g.
HouseholdIncome125K+,HouseholdSize2,etc.)marketSection Acategoryofaudiencesegmentsbasedonhousehold
characteristics.demographic Thetargetdemographic.demographicSection Thecategoryofthetargetdemographic.usAaPercentage TotalU.S.AverageAudiencePercentage(Thepercentageofthe
targetdemographicviewingtheaverageminuteoftheselectedprogramortimeperiodwithinthetotalU.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 CoverageAreaAverageAudiencePercentage(Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea.)
weightedViewingMinutes WeightedViewingMinutes(Theestimatedtotalnumberofviewing
minutesfortheprojectedaudienceofaspecificprogramortimeperiod.)
cvgSharePercentage CoverageAreaSharePercentage(Thepercentageofcoverageareahouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart.)
cvgHutPutPercentage CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionPercentage(Thepercentageofalltelevisionhouseholdswithinthecoverageareausingtheirtelevisionsetsduringtheaverageminuteofaspecifiedprogramortimeperiod.)
cvgHutPutProjUnits CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(Units)(Theprojectedestimateofalltelevisionhouseholdswithinthecoverageareausingtheirtelevisionsetsduringtheaverageminuteofaspecifiedprogramortimeperiod.)
cvgHutPutProj000 CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)(Theprojectedestimateofalltelevisionhouseholdswithinthecoverageareausingtheirtelevisionsetsduringtheaverageminuteofaspecifiedprogramortimeperiod,expressedinthousands.)
usUe000 TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.
cvgUe000 TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthenetwork’scoveragearea.
usIntab U.S.Intab(ThenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthetotalU.S.)
cvgIntab CoverageAreaIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
CommercialRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/analytics/api/v1/commercialRatings
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
sample(required) string Thesourcepanelfromwhichviewingiscollected.
• National
• Hispanic
startDate(required) string Thefirstdayofthemeasurementinterval(YYYY-MM-DD).Maximumof7dayspriortoenddate.
endDate(required) string Thelastdayofthemeasurementinterval(YYYY-MM-DD).Maximumof7daysafterstartdate.
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)startTime string Thestarttime(HH:MM)ofthedaypart.Earliest
timeis06:00;latesttimeis05:59.endTime string Theendtime(HH:MM)ofthedaypart.Earliest
timeis06:00;latesttimeis05:59.marketBreaks string Acommaseparatedlistofmarketbreaks
formattedasastring.TheinputvaluesshouldmarketbreakIDintegers,sourcedfromtheMarketBreaksAPI.Forexample:
• “0”(TotalComposite)• “94”(HispanicOrigin)• “0,94”(ReturnsratingsforbothTotal
CompositeandHispanicOrigin)Booleanexpressionscanalsobespecifiedformarketbreaks,includingAND,OR,NOToperators.Forexample:
• “52AND53”• “52AND53,(27AND29)OR36”
Note:Bydefault,theAPIwillreturntototalcompositemarketbreaksforeachsampletype.ForNationalsample,thatismarketbreak0(TotalComposite).ForHispanicsample,thatismarketbreak94(HispanicOrigin).
demographics(required) string Acommaseparatedlistofdemographics.TheinputvaluesshoulddemoAbbreviationvaluesandageranges.Forexample:
• “Household”
• “Persons18-49”• “Males35-54”• “Females55-999”• “Full-timeWorkingWomen18-54”
Maximumof38demographicsperrequest.
originators(required) string Originator,sourcedfromtheOriginatorsAPI.dataStreams(required) string Acommaseparatedlistofdatastreams.
Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+1”(Live+1Day–Includesallplaybackthatoccurredwithinonedayoftheliveairing).
• “Live+2”(Live+2Days–Includesallpalybackthatoccurredwithintwodaysoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+4”(Live+4Days–Includesallplaybackthatoccurredwithinfourdaysoftheliveairing).
• “Live+5”(Live+5Days–Includesallplaybackthatoccurredwithinfivedaysoftheliveairing).
• “Live+6”(Live+6Days–Includesallplaybackthatoccurredwithsixdaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
• “Live+8”(Live+8Days-Includesallplaybackthatoccurredwithineightdaysoftheliveairing).
• “Live+9”(Live+9Days–Includesallplaybackthatoccurredwithinninedaysoftheliveairing).
• “Live+10”(Live+10Days–Includesallplaybackthatoccurredwithintendaysoftheliveairing).
• “Live+11”(Live+11Days–Includesall
playbackthatoccurredwithelevendaysoftheliveairing).
• “Live+12”(Live+12Days-Includesallplaybackthatoccurredwithintwelvedaysoftheliveairing).
• “Live+13”(Live+13Days-Includesallplaybackthatoccurredwithinthirteendaysoftheliveairing).
• “Live+14”(Live+14Days–Includesallplaybackthatoccurredwithinfourteendaysoftheliveairing).
• “Live+15”(Live+15Days–Includesallplaybackthatoccurredwithinfifteendaysoftheliveairing).
• “Live+16”(Live+16Days–Includesallplaybackthatoccurredwithsixteendaysoftheliveairing).
• “Live+17”(Live+17Days-Includesallplaybackthatoccurredwithinseventeendaysoftheliveairing).
• “Live+18”(Live+18Days-Includesallplaybackthatoccurredwithineighteendaysoftheliveairing).
• “Live+19”(Live+19Days–Includesallplaybackthatoccurredwithinnineteendaysoftheliveairing).
• “Live+20”(Live+20Days–Includesallplaybackthatoccurredwithintwentydaysoftheliveairing).
• “Live+21”(Live+21Days–Includesallplaybackthatoccurredwithtwentyonedaysoftheliveairing).
• “Live+22”(Live+22Days-Includesallplaybackthatoccurredwithintwentytwodaysoftheliveairing).
• “Live+23”(Live+23Days-Includesallplaybackthatoccurredwithintwentythreedaysoftheliveairing).
• “Live+24”(Live+24Days–Includesallplaybackthatoccurredwithintwentyfourdaysoftheliveairing).
• “Live+25”(Live+25Days–Includesallplaybackthatoccurredwithintwentyfivedaysoftheliveairing).
• “Live+26”(Live+26Days–Includesallplaybackthatoccurredwithtwentysixdaysoftheliveairing).
• “Live+27”(Live+27Days-Includesall
playbackthatoccurredwithintwentysevendaysoftheliveairing).
• “Live+28”(Live+28Days-Includesallplaybackthatoccurredwithintwentyeightdaysoftheliveairing).
• “Live+29”(Live+29Days–Includesallplaybackthatoccurredwithintwentyninedaysoftheliveairing).
• “Live+30”(Live+30Days–Includesallplaybackthatoccurredwithinthirtydaysoftheliveairing).
• “Live+31”(Live+31Days–Includesallplaybackthatoccurredwiththirtyonedaysoftheliveairing).
• “Live+32”(Live+32Days-Includesallplaybackthatoccurredwithinthirtytwodaysoftheliveairing).
• “Live+33”(Live+33Days-Includesallplaybackthatoccurredwithinthirtythreedaysoftheliveairing).
• “Live+34”(Live+34Days–Includesallplaybackthatoccurredwithinthirtyfourdaysoftheliveairing).
• “Live+35”(Live+35Days–Includesallplaybackthatoccurredwithinthirtyfivedaysoftheliveairing).
Maximumof8datastreamsperrequest.
mediaSources(required) string Thecontributingplatformforviewing.• TVWithDigital• TV• Digital• Computer• Mobile• Tablet• Smartphone• PortableMediaPlayer• Others
contribution(required) string ThecontributingviewingfromVODwiththesameadloadaslineartelecast.
• LinearWithVOD• Linear• VOD
ratingMetrics string Acommaseparatedlistofratingmetrics.SpecifiesthemetricsprovidedintheAPIresponse.
• nccmUsAaPercentage(National
CommercialClockMinuteAverageAudiencePercentage=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(CoverageAreaIntab=Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’s
coveragearea.)
Allratingmetricswillbereturnedifthisparameterisnotspecifiedintherequest.
ResponseField DescriptionbroadcastDate Thedateonwhichthetelecastoriginallyaired(YYYY-MM-DD).sample Thesourcepanelfromwhichviewingiscollected.
• “National”• “Hispanic”
programId Auniquenumericalidentifierforanindividualprogramname.telecastId Auniquenumericalidentifierforanindividualtelecast.originator Abbreviatedoriginatorname.(e.g.“ABC”).trackageId Auniquenumericalidentifierprovidedbythenetworktotrack
eachtelecast.trackageName Auniqueidentifierprovidedbythenetworktotrackeachtelecast
(e.g.“NCISMARATH3P”tracksairingsofNCISthatoccurredonThursdaysat3PM).
summaryTypeCode Auniquecharacteridentifierforthetop-levelgenreclassification(e.g.“GD”=GeneralDrama).
detailedTypeCode Auniquecharacteridentifierforadetailedgenreclassification(e.g.“SD”=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)
reportedDuration Thedurationofthetelecastairing(minutes).nccmDuration Thedurationofcommercialairingswithinthetelecast(seconds).telecastReportStartTime Thestarttimeofthetelecast(HH:MM).calendarDayOfWeekName Thedayoftheweekduringwhichtheprogramaired(e.g.
“THURSDAY”).telecastReportEndTime Theendtimeofthetelecast(HH:MM).originatorType Typeoforiginator
• “Cable”• “Broadcast”• “Syndication”
programName Thefullprogramname.episodeName Atitleforanindividualepisodeofaprogram.feedPattern Thepatternofdeliveryforthetelecast.
• “B”–Broadcast• “L”–Live• “D”-Dual
specialIndicator “S”–SpecialProgrambreakoutIndicator “B”–BreakoutpremiereIndicator “P”-PremiererepeatIndicator “R”-RepeatgappedIndicator “G”-GappedsustainerIndicator “S”-SustainerliveIndicator “L”–Liveairingcontribution ThecontributingviewingfromVODwiththesameadloadaslinear
telecast.• LinearWithVOD• Linear• VOD
mediaSource Thecontributingplatformforviewing.• TVwithDigital• TV• Digital• Computer• Mobile• Tablet• Smartphone• PortableMediaPlayer• Others
dataStream Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.
• “Live”(Live-Includesviewingthatoccurredduringtheliveairing).
• “Live+SD”(Live+SameDay-Includesallplaybackthatoccurredwithinthesamedayoftheliveairing).
• “Live+1”(Live+1Day–Includesallplaybackthatoccurredwithinonedayoftheliveairing).
• “Live+2”(Live+2Days–Includesallpalybackthatoccurredwithintwodaysoftheliveairing).
• “Live+3”(Live+3Days-Includesallplaybackthatoccurredwithinthreedaysoftheliveairing).
• “Live+4”(Live+4Days–Includesallplaybackthatoccurredwithinfourdaysoftheliveairing).
• “Live+5”(Live+5Days–Includesallplaybackthatoccurredwithinfivedaysoftheliveairing).
• “Live+6”(Live+6Days–Includesallplaybackthatoccurredwithsixdaysoftheliveairing).
• “Live+7”(Live+7Days-Includesallplaybackthatoccurredwithinsevendaysoftheliveairing).
• “Live+8”(Live+8Days-Includesallplaybackthatoccurredwithineightdaysoftheliveairing).
• “Live+9”(Live+9Days–Includesallplaybackthatoccurredwithinninedaysoftheliveairing).
• “Live+10”(Live+10Days–Includesallplaybackthat
occurredwithintendaysoftheliveairing).• “Live+11”(Live+11Days–Includesallplaybackthat
occurredwithelevendaysoftheliveairing).• “Live+12”(Live+12Days-Includesallplaybackthat
occurredwithintwelvedaysoftheliveairing).• “Live+13”(Live+13Days-Includesallplaybackthat
occurredwithinthirteendaysoftheliveairing).• “Live+14”(Live+14Days–Includesallplaybackthat
occurredwithinfourteendaysoftheliveairing).• “Live+15”(Live+15Days–Includesallplaybackthat
occurredwithinfifteendaysoftheliveairing).• “Live+16”(Live+16Days–Includesallplaybackthat
occurredwithsixteendaysoftheliveairing).• “Live+17”(Live+17Days-Includesallplaybackthat
occurredwithinseventeendaysoftheliveairing).• “Live+18”(Live+18Days-Includesallplaybackthat
occurredwithineighteendaysoftheliveairing).• “Live+19”(Live+19Days–Includesallplaybackthat
occurredwithinnineteendaysoftheliveairing).• “Live+20”(Live+20Days–Includesallplaybackthat
occurredwithintwentydaysoftheliveairing).• “Live+21”(Live+21Days–Includesallplaybackthat
occurredwithtwentyonedaysoftheliveairing).• “Live+22”(Live+22Days-Includesallplaybackthat
occurredwithintwentytwodaysoftheliveairing).• “Live+23”(Live+23Days-Includesallplaybackthat
occurredwithintwentythreedaysoftheliveairing).• “Live+24”(Live+24Days–Includesallplaybackthat
occurredwithintwentyfourdaysoftheliveairing).• “Live+25”(Live+25Days–Includesallplaybackthat
occurredwithintwentyfivedaysoftheliveairing).• “Live+26”(Live+26Days–Includesallplaybackthat
occurredwithtwentysixdaysoftheliveairing).• “Live+27”(Live+27Days-Includesallplaybackthat
occurredwithintwentysevendaysoftheliveairing).• “Live+28”(Live+28Days-Includesallplaybackthat
occurredwithintwentyeightdaysoftheliveairing).• “Live+29”(Live+29Days–Includesallplaybackthat
occurredwithintwentyninedaysoftheliveairing).• “Live+30”(Live+30Days–Includesallplaybackthat
occurredwithinthirtydaysoftheliveairing).• “Live+31”(Live+31Days–Includesallplaybackthat
occurredwiththirtyonedaysoftheliveairing).• “Live+32”(Live+32Days-Includesallplaybackthat
occurredwithinthirtytwodaysoftheliveairing).• “Live+33”(Live+33Days-Includesallplaybackthat
occurredwithinthirtythreedaysoftheliveairing).
• “Live+34”(Live+34Days–Includesallplaybackthatoccurredwithinthirtyfourdaysoftheliveairing).
• “Live+35”(Live+35Days–Includesallplaybackthatoccurredwithinthirtyfivedaysoftheliveairing).
marketBreakId AuniquenumericalidentifierforaMarketBreak.marketBreak Anaudiencesegmentbasedonhouseholdcharacteristics(e.g.
HouseholdIncome125K+,HouseholdSize2,etc.)marketSection Acategoryofaudiencesegmentsbasedonhousehold
characteristics.demographic Thetargetdemographic.demographicSection Thecategoryofthetargetdemographic.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 CoverageAreaIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthetelevisionpanelacrossthenetwork’scoveragearea.)
SubmitBatchRequestAPIPOSTRequestURL:https://api.developer.nielsen.com/watchapi/batch/audience/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/audience/get-batch-status
HeaderName ParameterType
Description
Authorization(required) string APIaccesstokenprovidedbyNielsen.“Bearer<accesstoken>”
ParameterName ParameterType
Description
batchId(required) string Auniquenumericalidentifierforabatchrequest;sourcedfromtheSubmitBatchRequestAPI.
ResponseField DescriptionbatchId Auniquenumericalidentifierforabatchrequest.status Thestatusofasubmittedbatchrequest.
• Queued• Processing• Completed• Failed
GetBatchResponseAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/batch/audience/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.