nielsen local monthlies api release 1.0 documentation · stations description: station metadata for...

NielsenLocalMonthliesAPIRelease1.0Documentation

EndpointDetails: https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1

Ratelimit:3callspersecond

AuthenticationInstructions:Togenerateanaccesstoken,pleaseseetheOAuth2.0GuideonhowtousetheAuthorizationAPI.TomakeanAPIcall,passinthebelowheaderwithyouraccesstoken:

Key:“Authorization”

Value:“Bearer762CoxehAgJsCmRCTA6CIqUnQzwYOH20n9NMiJc6rm9xKrVMYH2oZD”

Note:Thereisaspaceandanaccesstokenafterbearer.Theaccesstokenmustbegenerated

usingtheauthorizationendpoint.

ExamplerequestinPostman:

dataAvailabilitiesDescription:DeterminewhatdataisavailableintheAPI(Datastreams,measurementperiods,sample

types,etc.)

RequestURL:https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/dataAvailabilities?

ParameterName ParameterType

Description

marketId Int UniqueDMAidentifier(e.g."501"forNew

York)

marketName String NielsenDMAname(e.g."NewYork,NY")

marketType String ThecollectionmethodoftheDMA(e.g."LPM",

"Set-Meter",“CodeReader”,“Diary”)

year Int Theyearcorrespondingtothemeasurement

period(e.g.“2015”)

month String Themonthcorrespondingtothemeasurement

period(e.g.“March”)

dataSource String Datasample(e.g.“Cable”,“Hispanic”,“Black”,

“Household”)

excludeUnsubscribedMarkets Bool Truebydefault.Whentrue,theresponsewill

belimitedtoonlymarketsthattheuseris

subscribedto.Iffalse,theresponsewillreturn

metadataforallmarkets.

ResponseField Description marketId UniqueDMAidentifier(e.g."501"forNewYork)

marketName NielsenDMAname(e.g.“NewYork,NY”)

marketType ThecollectionmethodoftheDMA(e.g.“LPM”,“Set-Meter”)

year Theyearcorrespondingtothemeasurementperiod(e.g.“2015”)

month Themonthcorrespondingtothemeasurementperiod(e.g.“March”)

dataSource Datasample(e.g.“Cable”,“Hispanic”,“Black”,“Household”)

surveyStartDate Firstbroadcastdateofthesurveyperiod(YYYY-MM-DD)

surveyEndDate Lastbroadcastdateofthesurveyperiod(YYYY-MM-DD)

markets

Description:MarketorDesignatedMarketArea(DMA)metadata.

RequestURL:https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/markets?

ExampleURL:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/markets?marketType=Diary


Description

marketId int UniqueDMAidentifier(e.g."501"forNew

York)

marketName String NielsenDMAname(e.g."NewYork,NY")

marketType String ThecollectionmethodoftheDMA(e.g."LPM",

"Set-Meter")

marketRank int ThecurrentrankoftheDMA(e.g."1"

correspondstothemostpopulatedDMA,New

York)





ResponseField

Description

marketId UniqueDMAidentifier(e.g."501"forNewYork)

marketName NielsenDMAname(e.g."NewYork,NY")

marketType ThecollectionmethodoftheDMA(“LPM”,“Set-Meter”,“CodeReader”,

“Diary”)

marketAbbr AbbreviatedDMAname(e.g."NY")

marketRank ThecurrentrankoftheDMA(e.g."1"correspondstothemostpopulated

DMA,NewYork)

stations

Description:Stationmetadataformarketswheretherehasbeenviewingofthestation.Includescume

dataforaspecifiedmeasurementperiodforthe7am-1amdaypart.

RequestURL:https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/stations?

ExampleRequest:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/stations?excludeSpill=false&market

Id=501


Description

stationId int Uniquestationidentifier.(e.g.5010)

stationName String Stationname/CallLetters(e.g.“WABC-TV7.2”)

affiliation String Networkaffiliationoflocalbroadcaststation

(e.g.“ABC”)

callLetters string Calllettersforthestation(e.g.WABC)

distributionType String Distributorstationtype(e.g.“Broadcast”or

“Cable”)

cumeThreshold Float Correspondsto“stationCume”–filtersoutall

stationswithstationCumebelowtheinput

value.Ifnull,thenthethresholdwillbe2.5

cumePeriod Date Ifnotspecified,mostrecentcumeperiodfor

eachstationisreturned.Ifspecified(e.g.YYYY-

MM-DD;2015-10-28),stationCumedataforthe

measurementperiodthatthedatefallsintois

returned(ornulliftherewasnocumeforthe

stationduringthatmeasurementperiod)

excludeSpill Bool Defaultstofalse.Controlswhetherornotto

returnbroadcaststationsoriginatingin

differentmarkets(e.g.“true”,“false”)

originMarketId int MarketIDoftheDMAwherethesource

originatedfrom

originMarketName String Nameofstation’soriginmarket(e.g.“New

York”)

marketId Int MarketIDoftheDMA(e.g.“501”forNY).

MarketIDscanberetrievedfromthedata

availabilityormarketsreferencecall)

marketName String NielsenDMAname(e.g.“NewYork,NY”)

parentPlusIndicator String Indicateswhetherastationisapartofa

Parent+relationship.OptionsareParent+

(denotingthesumofparentstationwith

satellites),Parent,Satellite,orOther(returns

onlystationswhicharenotapartofaparent+

relationship).





ResponseField Description stationId UniquenumericalStationIdentifier

stationName Stationname

callLetters Calllettersforthestation(e.g.WABC)

affiliation Networkaffiliationoflocalbroadcaststation

airChannel Stationairchannel

parentPlusIndicator Denoteswhetherastationispartofaparent+relationship.(e.g.

Parent+,Parent,Satellite,null)

distributionType Distributorstationtype(“Broadcast”or“Cable”)

stationCume Cumeforthemeasurementperiod.IfcumePeriodisnotspecified,it

shouldbethemostrecentcume.Ifnothresholdissetandthereisno

cumeforastation,thenanullshouldbereturned

cumePeriod MeasurementperiodforthestationCumereturned

originMarketId MarketIDoftheDMAwherethesourceoriginatedfrom

originMarketName DMAnamewherethesourceoriginatedfrom

marketId MarketIDoftheDMA(e.g.“501”forNY)

marketName NielsenDMAname

programsDescription:Programlineupmetadataforaspecifiedbroadcastday,market,andstation.

RequestURL:https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/programs?

ExampleURL:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/programs?broadcastDate=2016-04-

29&reportStart=03%3A00&reportEnd=03%3A00&marketId=501&stationId=5010


Description

broadcastDate(required)

Date Broadcastdayofrequesteddatainthefollowingformat:

YYYY-MM-DD(e.g.“2015-12-10”)

reportStart String Reportstarttime(e.g.HH:MM;“12:20”24-hourtime).

Optionalfield–defaultstoafullbroadcastday,03:00AM

–03:00AM.

reportEnd string Reportendtime(e.g.HH:MM;“13:20”24-hourtime).

Optionalfield–defaultstoafullbroadcastday,03:00AM

–03:00AM.

programId Int UniquenumericProgramIdentifier

programName String Programname.Thisparametercanbeusedasafilterand

searchesfortheclosestmatch(e.g.“Wheel”)

programSource String Networksourcefortheprogram(e.g.“FOX”)

stationId(required)

Int NumericalIDcodeofthestation(e.g.“5015”forWABC-TV

7.1intheNYDMA).StationIDcanberetrievedfromthe

stationsreferencecall

originMarketId Int MarketIDoftheDMAwherethesourceoriginatedfrom

(e.g.“501”)

marketId(required)

Int MarketIDoftheDMA(e.g.“501”forNY).MarketIDscan

beretrievedfromthedataavailabilityormarkets

referencecall)

telecastId int UniquenumericIdentifierforeachTelecast

trackageId Int TrackageIDtoprovideawayofidentifyingwhichairingof

thespecifictelecast

trackageName String Clientprovidednametotrackeachtelecast

ResponseField Description broadcastDate Thedateonwhichtheprogramoriginallyaired(YYYY-MM-

DD).

broadcastDayOfWeekName Thebroadcastdayoftheweekduringwhichtheprogram

aired(e.g.“THURSDAY”).

programId UniquenumericProgramIdentifier

programName ProgramName

telecastStartTime Localtimeforwhentheprogramstarts

telecastEndTime Localtimeforwhentheprogramends

totalDuration Totaldurationoftheprogram

telecastActualStartTime Actualstarttimeoftelecast(notquarter-hourbound)

telecastActualEndTime Actualendtimeoftelecast(notquarter-hourbound)

programTypeCode Broadcastspecialcodetodenotethetypeofprogram

programTypeDesc Describeswhattypeofprogramitis

programSource Networksourcefortheprogram

stationId NumericalIDcodeofthestation(e.g.“5015”forWABC-TV

7.1intheNYDMA).StationIDcanberetrievedfromthe

stationsreferencecall

stationName Stationname

callLetters Calllettersforthestation(e.g.WABC)

affiliation Networkaffiliationoflocalbroadcaststation

distributionType Distributorstationtype(“Broadcast”or“Cable”)

episodeId UniqueIDnumberforanepisode

episodeTitle Nameoftheepisode

telecastId UniquenumericIdentifierforeachTelecast

trackageId TrackageIDtoprovideawayofidentifyingwhichairingof

thespecifictelecast

trackageName Clientprovidednametotrackeachtelecast

originMarketId MarketIDoftheDMAwherethesourceoriginatedfrom

originMarketName DMAnamewherethesourceoriginatedfrom

marketId MarketIDoftheDMA(e.g.“501”forNY)

marketName NielsenDMAname

quarterHourRatingsDescription:Quarter-hourratingsmetricsforaspecifiedbroadcastday,market,station,datastream,

sampletype,anddemographic.

RequestURL:https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/quarterHourRatings?

ExampleURL:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/quarterHourRatings?broadcastDate

=2015-11-

28&reportStart=03%3A00&reportEnd=03%3A00&gender=Person&marketId=501&stationId=5015&data

Source=Household&dataStream=Live%2BSD&feedPatternCode=None


Description

broadcastDate(required) Date Broadcastdayofrequesteddatainthe

followingformat:YYYY-MM-DD(e.g.“2015-

12-10”)

reportStart string Reportstarttime(e.g.HH:MM;“12:20”24-

hourtime).Optionalfield–defaultstoafull

broadcastday,03:00AM–03:00AM.

reportEnd string Reportendtime(e.g.HH:MM;“13:20”24-



gender(required) string Genderofthetargetdemographic.

• “Households”

• “Person”

• “Male”

• “Female”

startAge Int Youngestageofthetargetdemographic

(e.g.IftargetdemographicisPersons18-34,

startAgewillbe18).

• 2(defaultifnostartAgeisspecified,

Availableforpersonsonly)

• 6(Availableforpersonsonly)

• 12

• 15

• 18

• 21

• 25

• 35

• 50

• 55

• 65

endAge Int Oldestageofthetargetdemographic(e.g.If

thetargetdemographicisPersons18-34,

endAgewillbe34).

• 5(PersonsOnly)

• 11(PersonsOnly)

• 14

• 17

• 20

• 24

• 34

• 49

• 54

• 64

• 999(defaultifnoendAgeis

specified)

dataStream Stream Time-shiftedviewingfromDVRPlaybackor

On-demandcontentwiththesame

commercialload.Ifnotespecified,Live+SD

willbethedefault.

• “Live”(Live-Includesviewingthat

occurredduringtheliveairing).

• “Live+SD”(Live+SameDay-Includes

allplaybackthatoccurredwithinthe

samedayoftheliveairing).

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

playbackthatoccurredwithinthree

daysoftheliveairing).


playbackthatoccurredwithinseven


feedPatternCode(required) String Definesfeedpatternofcalculations.(e.g.

“Live”,“Broadcast”,“Dual”,or“None”).

Defaultis“None”

dataSource(required) String Thesourcepanelfromwhichtheratings

metricsareprojected.

• "Household"-TotalHousehold

sample

• "Cable"-Wiredcablesample.When

ahouseholdiswiredforcable,e.g.

receivescableviaawiretothee

homefromacablehead-endlocated

inthecommunity.Ifahomeis

‘wired’toreceivecablechannelson

anyTVsetinthehomes,thenthe

homeisconsidereda‘wired’cable

home.

• "Hispanic"-NSIHHispanicsample.

AvailableforMiami,LosAngeles,

NewYork,andChicagomarkets.

deviceType string Tocontrolwhatdevicebreakoutsare

included.Ifnull,TVOnlyisreported.Device

typesinclude:

- TV:TVonly

- TV+Digital:AlldigitaldevicesplusTV

- TV+Mobile:Allmobiledevicesplus

TV

- TV+Computer:Computer(PCCensus)

plusTV

- Digital:Alldigitaldevices.Includes

tablets,smartphones,Personal

MediaPlayers(PMPs),and

computers(PCCensus)

- Mobile:Tablets,smartphones,and

PMPs

- Tablets:Tabletsonly

- Smartphones:Smartphonesonly

- PMPs:PortalMediaPlayersonly

- Computer:Computeronly(PC

Censusviewingonly)

metrics array[string] SpecifiesthemetricsprovidedintheAPI

response.

• aaPercentage-AverageAudience

Percentage=Thepercentageofthe

targetdemographicviewingthe

selectedstation,akaRating

• aaProjUnits–AverageAudience

expressedinunits

• aaProj000–AverageAudience

expressedinthousands

• sharePercentage-Thepercentof

HouseholdsorPersonsusing

televisiontunedtoaspecific

program/stationinthemarket

• hutPutPercentage-Thepercentage

ofalltelevisionshouseholdswithin

themarketusingtheirtelevisionsets

duringthespecifiedquarter-hour

• hutPutProjUnits-Theprojected

estimatesofalltelevisionhouseholds

withinthemarketusingtheir

televisionsetsduringthequarter-

hour

• hutPutProj000-Theprojected



televisionsetsduringtheaverage

minuteofaspecifictimeperiod,


• ue000-UniverseEstimate(UE)isthe

totalnumberofhouseholdsor

personswithinthetarget

demographicinthemarket

• intab-numberofhouseholdsor

personssupplyingusableinformation

withinthemarket

marketId(required) Int UniquenumericalidentifierfortheDMA

(e.g.“501”forNY).MarketIDscanbe

retrievedfromthe'dataavailability'or

'markets'referencecalls)

stationId(required) Int NumericalIDcodeofthestation–(e.g.

“5015”forWABC-TV7.1intheNYDMA).

StationIDcanberetrievedfromthe

'stations'referencecall.Maximumone

stationcanbepassedin.

programId Int Uniqueprogramidentifier(e.g.“12345”)


trackageId Int TrackageIDtoprovideawayofidentifying

whichairingofthespecifictelecast


ResponseField DescriptionbroadcastDate Thedateonwhichtheprogramoriginallyaired(YYYY-MM-

DD).



quarterHourStartTime Starttimeofthequarterhourrecord

quarterHourEndTime Endtimeofthequarterhourrecord

gender Genderoftheselecteddemographic.

startAge Startageofthedemographic(Persons,Males,Femalesonly)

endAge Endageofthedemographic(Persons,Males,Femalesonly)

dataStream Time-shiftedviewingfromDVRPlaybackorOn-demand

contentwiththesamecommercialload.

• “Live”(Live-Includesviewingthatoccurredduring

theliveairing).

• “Live+SD”(Live+SameDay-Includesallplayback

thatoccurredwithinthesamedayoftheliveairing).

• “Live+3”(Live+3Days-Includesallplaybackthat

occurredwithinthreedaysoftheliveairing).

“Live+7”(Live+7Days-Includesallplaybackthatoccurred

withinsevendaysoftheliveairing).

feedPatternCode Feedpattern(None,Live,Dual,Broadcast)

dataSource Thesourcepanelfromwhichtheratingsmetricsare

projected.

deviceType Tocontrolwhatdevicebreakoutsareincluded.Ifnull,TV

Onlyisreported.Devicetypesinclude:

- TV:TVonly


- TV+Mobile:AllmobiledevicesplusTV

- TV+Computer:Computer(PCCensus)plusTV

- Digital:Alldigitaldevices.Includestablets,

smartphones,PersonalMediaPlayers(PMPs),and

computers(PCCensus)

- Mobile:Tablets,smartphones,andPMPs




- Computer:Computeronly(PCCensusviewingonly)

marketId DMAID

marketName NameoftheDMA

stationId UniquenumericalstationIDcode.

stationName Callsign/nameofstation

programId Auniquenumericalidentifierforanindividualprogram

name.

programName Fullprogramname.



thespecifictelecast


aaPercentage AverageAudiencePercentage(e.g.,Rating)-Estimated

percentageoftheuniverseofTVhouseholds(orother

specifieddemographicgroup)tunedtoastationatthesame

time.

aaProjUnits AverageAudienceProjection(Units)-Theestimatednumber

ofviewersexpressedinunits(impressions).

aaProj000 AverageAudienceProjectioninthousands.

sharePercentage (Impressions/HUTorPUTImpression)*100ThepercentofHouseholdsorPersonsusingtelevisionwho

aretunedtoaspecificprogram,station,ornetworkina

specificareaataspecifictime.

hutPutPercentage HouseholdsUsingTelevision(HUT)Percent%isthe

percentageofalltelevisionhouseholdsinageographywith

oneormoresetsinuseduringaspecifictimeperiod.The

sumoftheaverageratingsforagiventimeperiodis

sometimeshigherthantheHUTnumberbecauseof

householdsviewingmultipleprogramsatthesametime.Ifa

householdiswatchingtwoprograms,itiscountedtoward

eachprogramratingbutonlyoncetowardaHUTnumber.

hutPutProjUnits HUT/PUTinunits.

hutPutProj000 HUT/PUTinthousands.

ue000 UniverseEstimate-thetotalnumberofhouseholdsand

persons2+withinthedesignatedcharacteristic,expressedin

thousands.

intab Thenumberofhouseholdsorpersonssupplyingusable

informationforthereport.

state Mandatoryexclusions=“@”

Belowminimumsamplesize=“*”(IfIntabisbelow45forHH

demographicor16forpersons)

programRatingsDescription:Programratingmetricsforaspecifiedbroadcastdate,market,station,datastream,sample,

anddemographic.

RequestURL:https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/programRatings?

ExampleURL:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/programRatings?broadcastDate=20

15-11-

28&reportStart=03%3A00&reportEnd=03%3A00&gender=Person&marketId=501&stationId=5015&data



Description



12-10”)







gender(required) string Genderofthetargetdemographic.

• “Households”

• “Person”

• “Male”

• “Female”

startAge Int Youngestageofthetargetdemographic

(e.g.IftargetdemographicisPersons18-34,

startAgewillbe18).

• 2(defaultifnostartAgeisspecified,

Availableforpersonsonly)

• 6(Availableforpersonsonly)

• 12

• 15

• 18

• 21

• 25

• 35

• 50

• 55

• 65

endAge Int Oldestageofthetargetdemographic(e.g.If

thetargetdemographicisPersons18-34,

endAgewillbe34).

• 5(PersonsOnly)

• 11(PersonsOnly)

• 14

• 17

• 20

• 24

• 34

• 49

• 54

• 64

• 999(defaultifnoendAgeis

specified)




willbethedefault.














Defaultis“None”




sample









home.






typesinclude:

- TV:TVonly



TV


plusTV




computers(PCCensus)


PMPs





Censusviewingonly)


response.






expressedinunits















hour













withinthemarket





stationId(required) Int NumericalIDcodeofthestation–(e.g.5015

forWABC-TV7.1intheNYDMA).StationID

canberetrievedfromthe'stations'

referencecall.Maximumonestationcanbe

passedin.



DD).









theliveairing).









projected.



- TV:TVonly






computers(PCCensus)






marketId DMAID




programId Auniquenumericalidentifierforanindividualprogramname

programName Fullprogramname

telecastStartTime Exacttimewhenthetelecaststarted

telecastEndTime Exacttimewhenthetelecastended

totalDuration Totaldurationoftheprogram

episodeId UniqueIDnumberforanepisode

episodeTitle Nameoftheepisode



thespecifictelecast





time.



















thousands.






quarterHourBulkRatingsDescription:Quarter-hourratingsmetricsforall26buildingblockdemographicsforaspecified

broadcastdate,market,station,datastream,andsample.

RequestURL:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/quarterHourBulkRatings?

ExampleURL:

https://api.developer.nielsen.com/watchapi/local/monthlies/api/v1/quarterHourBulkRatings?broadcast

Date=2015-11-28&reportStart=03%3A00&reportEnd=03%3A00&marketId=501&stationId=5015&data



Description



12-10”)










willbethedefault.














typesinclude:

- TV:TVonly



TV


plusTV




computers(PCCensus)


PMPs





Censusviewingonly)



Defaultis“None”




sample









home.





response.






expressedinunits















hour













withinthemarket





stationId(required) Int NumericalIDcodeofthestation–(e.g.5015

forWABC-TV7.1intheNYDMA).StationID

canberetrievedfromthe'stations'

referencecall.Maximumonestationcanbe

passedin.



trackageId Int TrackageIDtoprovideawayofidentifying

whichairingofthespecifictelecast



DD).



quarterHourStartTime Starttimeofthequarterhourrecord

quarterHourEndTime Endtimeofthequarterhourrecord







theliveairing).









- TV:TVonly






computers(PCCensus)








projected.

marketId DMAID




programId Auniquenumericalidentifierforanindividualprogram

name.

programName Fullprogramname.



thespecifictelecast





time.



















thousands.






nielsen local monthlies api release 1.0 documentation · stations description: station metadata for...

Documents