Basic Airings Use Cases

API updates and articles
  1. Documentation - API
  2. Product Use Cases
  3. Media Measurement
  4. Basic Airings Use Cases

Pulling a generic National Airings report (does not include impressions)

When a client is first on-boarded with the API, they usually ask what the most granular data is available. We will point them to the most granular and useful data available (National TV Airings).

After authenticating, run the below API call

https://api.ispot.tv/v4/metrics/tv/airings?page[size]=10000&filter[start_date]=2019-08-20&filter[end_date]=2019-09-02&filter[airing_type]=N,R&filter[national_only]=1&include=industry,brand,episode,show,genre,sub_genre,network,day_part,day_of_week&filter[airings_min]=1&sort=-airing_date_et&metrics[include_audience_lifetime]=0&metrics[include_airings]=1&metrics[include_audience]=1&metrics[include_audience_attention]=0&metrics[include_audience_demo]=0

 

  • tv/airings returns all airings with spend (if the client has access to those). No impressions

  • start and end date are inclusive

  • page[size] determines how many rows of data you get back per API call. Recommend to use the highest for airings. 10000

  • airing_type=N,R returns National and regional ads. For local ads use L.

  • national_only=1 applies to the reach of the advertiser. Use 1 for national brands

  • add includes to add various other data points that are useful &include=industry,brand,episode,show,genre,sub_genre,network,day_part,day_of_week

 

Pulling an audience impressions for National Airings report (includes impressions)

It will return the same data as above but with impressions data.

Replace tv/airings endpoint with audience/airings endpoint

https://api.ispot.tv/v4/metrics/audience/airings?page[number]=1&page[size]=100&filter[start_date]=2024-07-18&filter[end_date]=2024-07-31&filter[airing_type]=N,R&filter[national_only]=1&filter[industry]=407&filter[brand]=32382&filter[airings_min]=1&sort=-airing_date_et&metrics[include_audience_lifetime]=0&metrics[audience_demo_source]=HH&metrics[include_airings]=1&metrics[include_audience]=1&include=industry,brand,episode,show,genre,sub_genre,network,day_part,day_of_week

Things to note in API call.

  • audience/airings returns all airings with spend (if the client has access to those) AND impressions

  • start and end date are inclusive

  • page[size] determines how many rows of data you get back per API call. Recommend to use the highest for airings. 5000

  • airing_type=N,R returns National and regional ads. For local ads use L.

  • national_only=1 applies to the reach of the advertiser. Use 1 for national brands

  • add includes to add various other data points that are useful &include=industry,brand,episode,show,genre,sub_genre,network,day_part,day_of_week

 

Adding Demographic filters to TV or Audience calls 

Your existing TV/Audience 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/audience/airings?filter[start_date]=2021-07-01&filter[end_date]=2021-07-15&filter[demographic_gender]=M&filter[demographic_age]=18-45&filter[airing_type]=N,R&filter[national_only]=1

Please note, the default filters in the iSpot dashboard return all P18+ Demos for M and F. Sample API call below

 

https://api.ispot.tv/v4/metrics/audience/airings?page[number]=1&page[size]=100&filter[start_date]=2024-07-18&filter[end_date]=2024-07-31&filter[airing_type]=N,R&filter[national_only]=1&filter[demographic_gender]=M,F&filter[demographic_age]=18+&filter[airings_min]=1&sort=-airing_date_et&metrics[include_audience_lifetime]=0&metrics[audience_demo_source]=PL&metrics[include_airings]=1&metrics[include_audience]=1&include=industry,brand,episode,show,genre,sub_genre,network,day_part,day_of_week

 

Common FAQS

How many airing type are there in total, and how do we represent them in the filter[airing_type]? And what does Regional, Spot Cable, National Satellite means?

  • N, National: iSpot saw the creative airing appear in multiple markets at the same time & placement. This includes both broadcast and cable national airings. 

  • L, Local: iSpot did not see the creative airing appear in multiple markets at the same time and placement. It was likely seen during a local ad break via a broadcast affiliate. Currently, iSpot only returns impressions back for Seattle and Dallas DMA. 

  • SC, Spot cable: Same as local but the ad was seen on broadcast affiliate (ex: Comcast, Spectrum)

  • NS, National satellite: Same as local but the ad was seen on national satellite (ex: Dish, DirecTV)

  • R, Regional: iSpot currently reports regional creative airings for NFL games only. This is done by identify the ad airings by market for each game.

 
Will this match the iSpot Dashboard?

In short, yes. The Audience API call is equivalent to the brand's Airings level report. This would be the downloaded report under Media Measurement and Airings. If impressions don't match see below. 

Reasons why your impressions from the API are not matching the UI
  • Looking at the wrong part of the dashboard. The audience/airings call will only match the downloaded report under Media Measurement and Airings
    • Additionally, the impressions won't match the other parts of the dashboard such as network or spot because the impressions from those modules include impressions tied to airings and impressions NOT tied to airings. Audience/airings only returns impressions tied to airings
    • To match the other parts of the site, replace airings with the appropriate module ex, audience/spots, audience/networks, etc
  • Incorrect filters on audience airings (remember to filter for only airing types N and R, national_only=1)
  • Dates are not same between the UI and API