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


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


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


Description


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


Description


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


Description


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).



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


Description



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


Description



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


Description


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).







• “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).


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).



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


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.





• “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.





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


Description














startTime string Thestarttime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbespecified).



summaryTypeCode string Auniquecharacteridentifierforatop-levelgenreclassification;sourcedfromtheGenresAPI,responsefield“summaryTypeCode”.

dataStreams(required) string Time-shiftedviewingfromDVRPlaybackorOn-demandcontentwiththesamecommercialload.





• nccmUsAaPercentage(NationalCommercialClockMinuteAverageAudiencePercentage=ThepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)

• nccmUsAaProjUnits(NationalCommercialClockMinuteAverageAudienceProjection(Units)=TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)

• nccmUsAaProj000(NationalCommercialClockMinuteAverage

AudienceProjection(000)=TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.,expressedinthousands)

• nccmCvgAaPercentage(NationalCommercialClockMinuteCoverageAreaAverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteofaselectedprogramwithinanetwork’scoveragearea)









episodeofaprogram.

telecastId Auniquenumericalidentifierforanindividualtelecast.

originatorId Auniquenumericalidentifierforanindividualprogrammingoriginator.

originatorType Typeoforiginator• “Cable”• “Broadcast”• “Syndication”
















indicators Specialattributesattachedtoprogramsthatlet

youselectasetofdaysonwhichselectedprogramsairandalsopermitdroppingofspecials,breakouts,orprogramsoflessthanfiveminutes'duration.Forsyndication,youcanalsodroplong-termprograms.







• (N)=Non-Commercial(Appliedattheprogramortelecastleveltoindicatethatnonationaladsorsponsorshipswereincludedintheprogramortelecast).



• (P-A)=ProgramAcquired• (P-O)=ProgramOriginal• (R)=Repeat(Appliedtoanytelecastthat



• (U)=Umbrella• (V)=Various• (X)=UnorderedSustainer

• 1=LongTerm







nccmUsAaPercentage NationalCommercialClockMinuteAverageAudiencePercentage(ThepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)

nccmUsAaProjUnits NationalCommercialClockMinuteAverageAudienceProjection(Units)(TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.)

nccmUsAaProj000 NationalCommercialClockMinuteAverageAudienceProjection(000)(TheprojectednumberofhouseholdstunedorpersonsviewingtheaveragequalifiedcommercialminuteoftheselectedprogramwithinthetotalU.S.,expressedinthousands.)

nccmCvgAaPercentage NationalCommercialClockMinuteCoverageAreaAverageAudiencePercent(Thepercentageofthetargetdemographicviewingtheaveragequalifiedcommercialminuteofaselectedprogramwithinanetwork’scoveragearea.)

usUe000 TheUniverseEstimate(UE)isthetotalnumberofhouseholdsorpersonswithinthetargetdemographicacrossthetotalU.S.



cvgIntab CoverageIntab(Thenumberofhouseholdsorpersonssupplyingusableinformationwithinthe

televisionpanelacrossthenetwork’scoveragearea.)

nccmDuration NationalCommericalClockMinutesDuration(seconds)(Thetotalnumberofsecondsacrossqualifiedcommercialminuteswithinaselectedprogram.)

QuarterHourProgramRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/quarterHourRatings


Description







daypartId(required) string Auniquecharacteridentifierforanindividualdaypart;sourcedfromtheDaypartsAPI,responsefield“daypartId”.







startTime string Thestarttime(HH:MM)ofacustomdaypart(daypartId“CUSTOM”mustbe

specified).



summaryTypeCode string Auniquecharacteridentifierforatop-levelgenreclassification;sourcedfromtheGenresAPI,responsefield“summaryTypeCode”.











• usAaProj000(TotalU.S.AverageAudienceProjection(000)=The

projectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands)

• usSharePercentage(TotalU.S.SharePercentage=Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart)



• usHutPutProj000(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands)


• cvgAaPercentage(CoverageArea

AverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea)

• cvgSharePercentage(CoverageAreaSharePercent=Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea)



• cvgHutPutProj000(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevisionProjection(000)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)



• usIntab(U.S.Intab=Thenumberofhouseholdsorpersonssupplying

usableinformationwithinthetelevisionpanelacrossthetotalU.S.)






episodeofaprogram.telecastId Auniquenumericalidentifierforanindividual

telecast.originatorId Auniquenumericalidentifierforanindividual

programmingoriginator.originatorType Typeoforiginator









daypartId Auniquecharacteridentifierforanindividual

daypart.








indicators Specialattributesattachedtoprogramsthatletyouselectasetofdaysonwhichselectedprogramsairandalsopermitdroppingofspecials,breakouts,orprogramsoflessthanfiveminutes'duration.Forsyndication,youcanalsodroplong-termprograms.







• (N)=Non-Commercial(Appliedattheprogramortelecastleveltoindicatethatnonationaladsorsponsorshipswere

includedintheprogramortelecast).



• (P-A)=ProgramAcquired• (P-O)=ProgramOriginal• (R)=Repeat(Appliedtoanytelecastthat



• (U)=Umbrella• (V)=Various• (X)=UnorderedSustainer• 1=LongTerm




intervalOfBroadcastDayId Anumericalidentifierforthesequentialquarterhourofthebroadcastday(e.g.52=intervalof18:00-18:15basedonthe06:00-06:00broadcastday).

intervalStartTime Thestartminuteofthetelecastwithinthequarterhourinterval.

intervalEndTime Theendminuteofthetelecastwithinthequarterhourinterval.

intervalDuration Thedurationofthetelecastwithinthequarterhourinterval.





• “Live+7”(Live+7Days-Includesall

playbackthatoccurredwithinsevendaysoftheliveairing).






usHutPutPercentage TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent(ThepercentageofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod.)





cvgSharePercentage CoverageAreaSharePercent(Thepercentageof

householdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea.)








TimePeriodRatingsAPIGETRequestURL:https://api.developer.nielsen.com/watchapi/national/api/v2/timePeriodRatings


Description



period(YYYY-MM-DD).

endDate(required) string Thelastdayofthedesiredreportingperiod



viewingSourceId(required) integer Auniquenumericalidentifierforanindividualviewingsource;sourcedfromtheViewingSourcesAPI,responsefield“viewingSourceId”.

daypartIds string Acommaseparatedlistofcharacteridentifiersfordayparts;sourcedfromtheDaypartsAPI,responsefield“daypartId”.







timePeriods string Acommaseparatedlistofstarttimeandendtimevaluesforcustomtimeperiods(e.g.06:00-06:59,13:00-14:29)








ratingMetrics(required) string Acommaseparatedlistofratingmetrics.

SpecifiesthemetricsprovidedintheAPIresponse.



• usAaProj000(TotalU.S.AverageAudienceProjection(000)=Theprojectednumberofhouseholdstunedorpersonsviewingaprogram/originator/daypartduringtheaverageminute,expressedinthousands)

• usSharePercentage(TotalU.S.SharePercentage=Thepercentageofhouseholdstuningorpersonsviewingthataretunedtoaspecificprogram/originator/daypart)



• usHutPutProj000(TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevision

Projection(000)=TheprojectedestimatesofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteofaspecifictimeperiod,expressedinthousands)


• cvgAaPercentage(CoverageAreaAverageAudiencePercent=Thepercentageofthetargetdemographicviewingtheaverageminuteofaselectedprogramortimeperiodwithinanetwork’scoveragearea)

• cvgSharePercentage(CoverageAreaSharePercent=Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea)



• cvgHutPutProj000(CoverageAreaHouseholdsUsingTelevision/PersonsUsingTelevision

Projection(000)=Theprojectednumberofhouseholds(HUT)orpersons(PUT)usingtelevisionwithinacablenetwork’scoveragearea,expressedinthousands.)





ResponseField DescriptionviewingSourceId Auniquenumericalidentifierforanindividual

viewingsource.viewingSourceName Fullviewingsourcename(e.g.“HOMEAND

GARDENTV”).sample Thesourcepanelfromwhichtheratingsmetrics

areprojected.• “National”• “Hispanic”






• “LF”(LateFringe-M-Su11P-6A)

• “WED”(WeekendDaytime-Sa-Su6A-



startTime Thestarttimeofatimeperiod(HH:MM:SS)endTime Theendtimeofatimeperiod(HH:MM:SS) dataStream Time-shiftedviewingfromDVRPlaybackorOn-

demandcontentwiththesamecommercialload.• “Live”(Live-Includesviewingthat

occurredduringtheliveairing).• “Live+SD”(Live+SameDay-Includesall

playbackthatoccurredwithinthesamedayoftheliveairing).








usHutPutPercentage TotalU.S.HouseholdsUsingTelevision/PersonsUsingTelevisionPercent(ThepercentageofalltelevisionhouseholdswithinthetotalU.S.usingtheirtelevisionsetsduringtheaverageminuteof

aspecifictimeperiod.)





cvgSharePercentage CoverageAreaSharePercent(Thepercentageofhouseholdsorpersonsusingtelevision(HUT/PUT)viewingaparticularprogramortimeperiodwithinaspecificcoveragearea.)





cvgUe000 TheCoverageUniverseEstimateisthetotalnumberofhouseholdsorpersonswithinthe

targetdemographicacrossthenetwork’scoveragearea.



SubmitBatchRequestAPIPOSTRequestURL:https://api.developer.nielsen.com/watchapi/batch/national/submit-batch-request


Description



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


Description


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.


Description



Description

batchId(required) string Auniquenumericalidentifierforabatchrequest;sourcedfromtheSubmitBatchRequestAPI.

ResponseField DescriptionbatchId Auniquenumericalidentifierforabatchrequest.status Thestatusofasubmittedbatchrequest.

• Completed• Failed

body JSONresponsecontenttransferredasaZipfile.

national api technical referencev1.9 - nielsen api portal · pdf filenielsen national tv...

Documents