API filters & includes

API updates and articles
  1. Documentation - API
  2. Best Practices
  3. API filters & includes

Most Commonly Used Filters


Spot Type
Name: filter[spot_type]
Description: Comma delimited list of Spot Types.

'1' - Commercial
'2' - Show Promo
'3' - Movie Trailer
'4' - Infomercial
'5' - Public Service Announcement
'6' - Network Movie Promo

Ex. For commercials use filter[spot_type]=1

 

Date Filters
filter[start_date]=2021-04-01
filter[end_date]=2021-04-14

Filter Airing Type
filter[airing_type]=N,R,L,SC,NS

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

filter[national_only]=1   (Filter[national_only]=0 applies to the reach of the advertiser not the reach of the spot)
filter[industry]=id
filter[brand]=id
filter[spot]=id
filter[airing]=id
filter[network]=id
filter[access]=1
filter[spot_type]=#
filter[airing]=id
filter[product]=id
filter[language]=en,es (english,spanish)
filter[product_type]=primary,secondary,competitive 

 

iSpot API also allows a user to return additional metadata that will add extra granularity to any API call.

List of valid includes
industry
brand
episode
show
genre
sub_genre
network
day_part
day_of_week
brand.parent
industry.parent
 

Filter accepts comma separated list
Ex: include=industry,brand,episode,show,genre,sub_genre,network,day_part,day_of_week

 

Group By

Group_by:
name: filter[group_by]=
in: query
description: Indicates how the results should be grouped.

  • I - Industry

  • P - Parent Brand

  • B - Brand

  • A - Spot

  • C - Creative

  • N - Network

  • S - Show

  • E - Episode

  • H - Schedule

  • W - Day of Week

  • D - Day Part

  • T - Date (EST takes into account daylight savings)

  • M - Month

  • K - Week

  • G - Sub-Genre

  • F - Genre

  • R - Duration

  • Y - Delta Date

Sort

sort:
name: sort=
in: query
description: Comma separated list of fields to sort. Prefix with a - to sort descending. Default sort direction is ascending.

        week

        'month'                                     

        'day_of_week'                               

        'day_part'                                  

        'date'                                       

        'airing_date'                              

        'airing_date_et'                            

        'airing_date_pt'                            

        'est_spend'                                 

        'conversions'                               

        'conversions_matched'                       

        'conversions_tv_population'               

        'conversion_rate'                           

        'conversion_rate_matched'                   

        'conversion_rate_tv_population'