Basic Reach and Frequency API Call

The most basic call to return Reach and Frequency for UM/OTT. It requires a brandid which can be found using the API call https://api.ispot.tv/v4/brands?filter[access]=1&include=parent,industry&sort=id&page[size]=10000

https://api.ispot.tv/v4/metrics/impressions/ott?filter[brand]=brandid&sort=-impressions_reach_percent_ott&filter[airing_type]=N,R&filter[national_only]=1

This will return cumulative R/F and impressions for OTT.  

 

 

Reach and Frequency by Publisher

You can add group bys to add more granularity. filter[group_by]=

 

https://api.ispot.tv/v4/metrics/impressions/ott?page[number]=1&page[size]=5000&filter[start_date]=2021-05-05&filter[end_date]=2021-06-03&filter[airing_type]=N,R&filter[national_only]=1&filter[demographic_gender]=M,F&filter[demographic_age]=18+&filter[brand]=brandid&filter[group_by]=P&sort=-impressions_reach_percent_ott

 

 

Currently Supported Groupbys:

filter[group_by]=T (Date cumulative)

filter[group_by]=P (Publisher)

filter[group_by]=P,CR (Publisher and Creative ID)

filter[group_by]=P,PL (Publisher and Placement ID)

filter[group_by]=P,SO (Publisher and OTT Source)

filter[group_by]=P,DSP (Publisher and DSP)

 

 

Filters

See below for a full list of API calls to pull the list of ids, along with filters, and group bys. 

Publisher/publisher ID  https://api.ispot.tv/v4/publishers/extended?filter[brand]=brandid

filter[publisher_id]=id

Placement ID https://api.ispot.tv/v4/client/ott/placements?filter[brand]=brandid

filter[client_placement_id]=id

Creative ID https://api.ispot.tv/v4/client/ott/creatives?filter[brand]=brandid

filter[client_creative_id]=id

Campaign ID https://api.ispot.tv/v4/campaigns/ott?filter[brand]=brandid

filter[campaign]=id

Source ID  https://api.ispot.tv/v4/client/ott/sources?filter[brand]=brandid

filter[source_id]=id

DSP https://api.ispot.tv/v4/client/ott/dsp?filter[brand]=brandid

filter[client_dsp_source]=id

Linear Spot  https://api.ispot.tv/v4/spots/extended?filter[start_date]=YYYY-MM-DD&filter[end_date]=YYYY-MM-DD&filter[airing_type]=N,R&filter[national_only]=1&filter[brand]=brandid&filter[group_by]=A&page[size]=10000&metrics[require_airings]=0&include=brand.parent,brand.industry.parent&sort=spot_title

filter[spot]=id

Linear Creative  https://api.ispot.tv/v4/spots/extended?filter[start_date]=YYYY-MM-DD&filter[end_date]=YYYY-MM-DD&filter[airing_type]=N,R&filter[national_only]=1&filter[brand]=brandid&filter[group_by]=C&page[size]=10000&metrics[require_airings]=0&sort=spot_title

filter[creative]=id

 

Adding Demographic filters to OTT calls 

Your existing OTT calls will continue to work as-is, returning household demographics.

Additional filtering can be applied with two new parameters:

filter[demographic_gender]
and

filter[demographic_age]

filter[demographic_gender] supports a comma separated list of M or F. When filter[demographic_gender] is not provided, the default of filter[demographic_gender]=M,F is applied

filter[demographic_age] supports closed and open age ranges. For example filter[demographic_age]=18-65 can be provided to explicitly request an age range of 18-65.  If an [demographic_age] boundary is missing, it is assumed to be either the smallest or largest possible set. For example [demographic_age]=-36 would include all filters below and inclusive of age 36. [demographic_age]=45- would include all filters above and inclusive of age 45.

Note that while any age can be provided, the ages will be expanded to match demo breaks of 18-64 every 5 years, 65-74, and 75+
Additionally, demographics data is only available through 2020-01-01, with household data available prior to that.

Example: OTT summary data for Male aged 18-45:
https://api.ispot.tv/v4/metrics/impressions/ott?filter[start_date]=2020-07-01&filter[end_date]=2020-07-15&filter[demographic_gender]=M&filter[demographic_age]=18-45 

 

Demographic filtering by age/gender is available for three gender selections and 11 distinct age breaks.

 

Age breaks can be combined to form a larger, continuous age group. For example, you can select Male age 18-29 and Female 40+. P2+ cannot be combined with other age or gender combinations.

Adding Linear Network Filters to OTT Calls 

The use case is that brands and networks want to compare the impressions, reach, and frequency between OTT and a linear network or network family. It gives a better read on the incrementallity and overlap when applying a more “true to the campaign” comparison, as opposed to always comparing OTT (or specific publishers) against all of linear TV

To get full list of available network families and networks, use API call https://api.ispot.tv/v4/networks/family?filter[access]=1

filter[network]=id

filter[network_family]=id 

Ex. AMC Parent and AMC Network

filter[network_family]=3&filter[network]=697

 

A complete API call with 18+ Demos and AMC Parent and AMC Network filters

https://api.ispot.tv/v4/metrics/impressions/ott?page[number]=1&page[size]=100&filter[start_date]=2022-06-23&filter[end_date]=2022-07-06&filter[airing_type]=N,R&filter[national_only]=1&filter[demographic_gender]=M,F&filter[demographic_age]=18+&filter[brand]=brandid&filter[network_family]=3&filter[network]=697&filter[group_by]=publisher&sort=-impressions_ott

Please note: Only 1 network family can be selected at a time but within that family, one or multiple networks from said family can be filtered on at the same time.