API v4 Release Notes

API updates and articles

Changelog

All notable changes to the API v4 is documented in this page, in reverse chronological order by release.

 

v4.31.2 - Jan 23, 2024

Maintenance release

**Task

   *Misc Improvements


v4.31.1 - Jan 17, 2024

Maintenance release

**Task

    *Misc Improvements


v4.31.0 - Dec 7, 2023

Maintenance release

**New Feature

  *Updates to support new Streaming Competitive module

   *endpoint: /v4/metrics/competitive 

 


v4.30.0- Dec 5, 2023

Maintenance release

**Task

    **OTT Conversions are now deduped if the same media is tagged with different sources. Only Direct OTT sources will return conversions. 


v4.29.4- Nov 2, 2023

Maintenance release

**Task

    * Misc Improvements


 

v4.29.3 - October 30, 2023

Maintenance release

**Bug Fix

    *OTT Publisher & Reach > Reach Count columns no longer shows '0' when Segment filter applied


 

v4.29.0 - October 4, 2023

 

**New Feature

  *Updates to support new Streaming Verification module

   *endpoint: /v4/metrics/verified/audience

 


v4.28.11 -July 19, 2023

Maintenance release

**Task

    * Misc Bug Fixes


 

v4.28.10 -July 12, 2023

Maintenance release

**Task

    * dashboard UM OTT Conversions are no longer obfuscated is under 100 in the overview section


 

v4.28.9 -June 7, 2023

Maintenance release

**Task

    * Misc Improvements


 

v4.28.8 - May 18, 2023

Maintenance release

**Task

    * Misc Improvements


 

v4.28.7 - May 11, 2023

Maintenance release

**Task

    *rate limit for metric, spots, and show endpoints have been increased


 

v4.28.4 - April 21, 2023

Maintenance release

**Bug Fix

    *500 errors on certain endpoints


 

v4.28.3 - April 11, 2023

Maintenance release

**Bug Fix

    *duplicate opt-out postings would cause 500 errors


 

v4.28.2 - April 4, 2023

Maintenance release

**Bug Fix

    *campaigns/ott endpoint incorrectly limiting date ranges
    *api request without bearer token would return “Error: Call to a member function getAccount() on null” rather than Unauthenticated

**Task

    *rate limit for metrics/impressions/ott has been increased to 50 requests per 60 seconds


v4.28.1 - March 28, 2023

Maintenance release

**Bug Fix

    *v4/audience/airings did not include person level impressions with default filters


v4.27.1 - January 31, 2023

Maintenance release


v4.27.0 - January 20, 2023

Maintenance release

**Bug Fix

    *ott endpoint was throwing 500 error when filtering for segments after 7/1

**Improvement

    *audience and ott endpoints can now filter for ages 2+

    *for default household filters, impression percentages have been removed and replaced with counts


v4.26.2 - January 10, 2023

Maintenance release

**Bug Fix

    *campaigns/ott endpoint was incorrectly filtering by date

         * Passing date range to `campaigns/ott` endpoint will filter response correctly now


v4.26.1 - Dec 12, 2022

Maintenance release

**New Feature

    *Add sorting support for publisher and impressions for UM Lift

         * endpoint: /v4/metrics/conversions/{SITE_ID}/ott/lift/publisher

              sort=publisher
              sort=-publisher
              sort=impressions_ott
              sort=-impressions_ott


v4.25.7 - Dec 5, 2022

Maintenance release

**New Feature

    *Add dynamic filters to network families bases on data availability

         * endpoint: /v4/networks/family/extended

              filter[network_family]
              filter[advertiser_id]
              filter[start_date]
              filter[end_date]
              filter[is_parent]


v4.25.6 - Nov 28, 2022

Maintenance release

**Bug

    */v4/campaigns/ott endpoint did not respect date ranges for accounts with date restriction

   


v4.25.3 - Oct 21, 2022

Maintenance release

**Improvements

    *Add new endpoint to list episodes

         * endpoint: /v4/episodes and /v4/episodes/{id}


v4.25.2 - Aug 30, 2022

Maintenance release

**Improvements

    *Add new network family filters and includes:

         * endpoint: /v4/networks/family

              include=brand
              include=history
              
include=network
              filter[networkFamily]
              filter[is_parent]
              filter[networkFamily]


v4.25.1 - Aug 22, 2022

Maintenance release

** Misc Bug Fix


v4.25.0 - Aug 11, 2022

Maintenance Release

**Improvement

   *update the US TV household population value for 2020 (120.1M) and 2021 (121.5M)

          * Impacts all of media measurement, conversions, unified measurement, segments and attention (impression values)


v4.24.3 - Aug 8, 2022

Maintenance release

** Improvement

    * Add “sub_type" to non-metrics Endpoints in order to return auto tier.

    * Example Endpoint: https://api.ispot.tv/v4/spots/[insert-ad-id]?include=type,sub_type

        "sub_type": {
            "data": {
                  "id": 101,
                  "label": "Tier 2"
             }
          }

** Internal framework update


v4.24.2 - Aug 2, 2022

Maintenance release


v4.24.1 - Jul 21, 2022

Maintenance release

** Internal framework update


v4.24.0 - Jul 14, 2022

Maintenance release

** Feature release

    * Introduced Linear network and network family filters to Unified Measurement

    * Further documentation

    * 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 


v4.23.14 - Jun 27, 2022

Maintenance release

** Misc bug fixes


v4.23.13- May 23, 2022

Maintenance release

** Bug

     * Update OTT Lift API to return the new OTT Raw Impression count


v4.23.12- May 5, 2022

Maintenance release

** Misc bug fixes


v4.23.11- April 25, 2022

Maintenance release

** Improvement
    * OTT Reach as a count has been added to the OTT Endpoints
    * filter[language]=es can now be used on /networks and /networks/extended


v4.23.9- April 4, 2022

Maintenance release

** Improvement
    * rate_sov column in conversions endpoint will always show up even if values are null


v4.23.7- March 21, 2022

Maintenance release

** Improvement
    * product ids can be filtered in the product-categories endpoint (example below)

/v4/product-categories?include=brand,industry,product&filter[product_type]=primary&filter[product_id]=2478


v4.23.5- March 3, 2022

Maintenance release

** Improvement
    * product urls are added to product block


v4.22.0- January 25, 2022

Feature release

** Calculations for UM calculates using 122.8 million UM population instead of 116 million
** new group by was added for OTT endpoints to allow for non cumulative impressions filter[group_by]=date_incremental or filter[group_by]=TI


v4.20.1- January 10, 2022

Feature release

** New endpoint to expose partner brand mapping rules to partners


 

v4.20.0- January 06, 2022

Feature release

** UM Lift is available
** endpoint is /v4/metrics/ott/{site_id}/lift/summary or /v4/metrics/ott/{site_id}/lift/publisher


 

v4.19.1- December 07, 2021

Maintenance release

** Misc bug fixes


v4.19.0- November 12, 2021

Feature release
Filters for Demo have been added to audience and tv endpoints. Examples here


v4.18.4- November 01, 2021

Maintenance release
** Bug
    *fixed bugs with customdata filters
    *v4/brands/extended/ott correctly now returns no brands if there are 0 brands available
    *Lift details filters added to developer site documentation

** Task
    *Holding Companies added to agency types.


v4.18.3- October 10, 2021

Maintenance release
** Bug
    *fixed some bugs with creative filter
** Improvement
    *Universal API > Airings > Add support for metrics[include_sov]


v4.18.1- September 20, 2021

Maintenance release
** Bug
    *v4/metrics/tune-in/show endpoints would sometimes return a 500 error
** Improvement
    *v4/product-categories now has ?include=products
    *v4/products now has ?include=product-category


v4.18.0 - August 27, 2021

Feature release
Enable iSpot dashboard and Ace Live seamless user experiences


v4.17.8 - August 23, 2021

Maintenance release
** Task
    *v4/shows?include=details returns additional metadata 
    *General bug fixes and improvements to extended endpoints
    *v4/client/ott/dsp?[brand_id] and v4/client/ott/device?filter[brand_id] have been added as new endpoints


v4.17.7 - August 10, 2021

Maintenance release

** Bug
    * lift/spots/details will now return date


v4.17.6 - July 20, 2021

Maintenance release

** Bug
    * filter[schedule]=<schedule_id> can be used for v4/shows/extended endpoint
    * include=contacts can be used for v4/brands endpoint to return contact information for both brand and agency

 


v4.17.4 - June 23, 2021

Maintenance release

** Improvement
    * filter[spot]=<spot_id> can be used for v4/spots/updates endpoint


v4.17.3 - June 7, 2021

Maintenance release

 

** Bugfix
    * Passing Start Min should return data. Moving date ahead one date will return data.
    * /v4/metrics/conversions/{ID}/lift/availability will return availability of data


v4.17.2 - June 3, 2021

Maintenance release

** Bugfix
    * Meta response min/max will always be provided

** Improvement
    * /brands/ endpoint will now return custom industry brands
    * /conversions/dates/last endpoint uses a more reliable data source


v4.17.1 - May 25, 2021

Maintenance release

** Bugfix
    * Pagination meta was incorrect in /metrics/impressions/ott respones
    * metrics[include_counts]=1 now works for /v4/metrics/*/dma endpoint

** Improvement
    * filter[brand]=<brand_id> can be used for /v4/products endpoint


v4.17.0 - May 18, 2021

Feature release

Improved grouping behavior for ott endpoints to support double group_by

For example, grouping by publisher with a sub-grouping of creative: v4/metrics/impressions/ott?filter[group_by]=publisher,creative


v4.16.0 - May 06, 2021

Feature release

New parameters added to /metrics/impressions/ott to control cumulative impression aggregation periods. Applying larger aggregation periods can improve performance considerably over the default daily aggregation. 

[filter]aggregation_start
[filter]aggregation_period

aggregation_start takes a numerical day of the week, where 1 is monday and 7 is sunday
aggregation_period takes the number of days. Like 1, 3, 7, etc…

This is only applicable when grouping by 'date'

 


v4.15.2 - April 26, 2021

Maintenance release

** Bugfix
    * /v4/spots/{id}?include=airing_parent_summary,airing_summary fixed an issue where airing dates were sometimes inconsistent with dates returned from /metrics endpoints


v4.15.1 - April 19, 2021

Maintenance release

** Improvement
    *  v4/[tv|audience|attention]/compare/ endpoints now fully serviced by new data engine 


v4.15.0 - April 13, 2021

Feature release

Spot level filtering for movies added to OTT demographics filters. filter[fandango_id] can now be used in combination with filter[demographic_age] and filter[demographic_gender]


v4.14.1 - March 29, 2021

Maintenance release

** Improvement
    * v4/networks/new endpoint added. This provides a way to see new networks which have been added within iSpot
    * v4/metrics/conversions/dates/last performance improvements


v4.14.0 - March 16, 2021

Feature release

Our extrapolation update implements highly tuned demographic balancing by age, gender, income, and education. It also balances for primary and secondary devices in the home, providing a more accurate count of TVs per household.

Our spend estimation is now CPM-based. This methodology uses our new extrapolated impressions to assign highly accurate spend value. We achieve this by using a series of hierarchical models that maximize accuracy based on available data.

All /metrics/ endpoints within API V4 are now considered 100% production ready and serviced by the updated data engine.


v4.13.0 - March 10, 2021

Feature release

** Improvement
    * /v4/conversions/{id}/lift/spots added. Lift can now by grouped by spot, in addition to day-parts, networks, and networkfamilies


Feb 26, 2021

TLS 1 and 1.1 no longer supported


v4.11.4 - Feb 23, 2021

Maintenance release

** Improvement
    * /v4/airings/updates can now filter by airing ID using filter[occurrence_id]
    * /v4/spots/{id} now supports product include via ?include=brand.product

** Bug
    * v4/metrics/conversions/{id}/summary endpoint could throw an error in some cases
    * airings timestamps were not correctly offset to pst/est


v4.11.3 - Feb 02, 2021

Maintenance release

** Internal framework update


v4.11.2 - Jan 19, 2021

Misc bug fixes and OTT performance improvements


v4.11.1 - Dec 29, 2020

Misc bug fixes


v4.11.0 - Dec 17, 2020

Feature release

** Improvement
    * OTT > Add demographics filters

Introducing demographics filters to most OTT endpoints. 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:
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 

 


v4.10.3 - Dec 8, 2020

Maintenance release

** Bug
    * Lift > Network Families were listed incorrectly in some cases
    * Access > Spot Download access issue


v4.10.2 - Nov 30, 2020

Maintenance release

** Miscellaneous bug fixes and improvements


v4.10.1 - Nov 23, 2020

Maintenance release

** Improvement
    * OTT > add view_completion_wear_percentile sort
    * Conversion Frequencies > Performance improvement when getting range of dates


v4.10.0 - Nov 17, 2020

Feature release

** Improvement
    * Attention > view_completion.index now represents the interruption rate rather than the completion rate
    * Attention > view_completion.avg_index *new* provides added context of seeing how ads perform across an entire industry,

Introducing cumulative creative wear. Cumulative creative wear can be seen when filtering to a single creative grouped by Time

For example, to see the daily cumulative creative wear for creative ID 123456789:
/v4/metrics/attention/dates?filter[start_date]=2020-07-01&filter[end_date]=2020-07-13&filter[creative]=123456789


v4.9.2 - Nov 09, 2020

Maintenance release

** No external changes


v4.9.1 - Nov 02, 2020

Maintenance release

** Improvement
    * /v4/airings/updates > return the change_type field


** Bug
    * Misc bug fixes


v4.9.0 - Oct 20, 2020

Feature release

** Improvement
    * Data Engine > Movie Conversions
    * OTT > Dates > Apply default group by
    * Misc bug fixes


v4.8.4 - Oct 05, 2020

Maintenance release

** Improvement
    * Segments > improvements to site listings endpoint
    * Remove metrics.include_audience_viewrate (attention 1.0)


Infrastructure - Oct 01, 2020

Enforce HTTPS on all calls with 301 redirect in place


v4.8.3 - Sept 30, 2020

Maintenance release

** Improvement
    * Media Measurement > Add Custom ID and Custom Title element to spot element


v4.8.2 - Sept 21, 2020

Maintenance release

** Bug
    * Attention > Creative wear not to become N/A when index is null

** Improvement
    * Airing Updates > Add filters for update types

 


v4.8.1 - Sept 14, 2020

Maintenance release

** Bug
    * OTT > Fixed access bug when specifying a campaign ID
    * Global > Do not include Regional when national_only: 1 is set 

** Task
    * Lift > Network by Day > Return model parameter

 


v4.8.0 - Sept 02, 2020

Feature release

** Improvement
    * Attention > Added view_completion (AKA "attention 3.0")

This adds new view_completion section to the response.
Supports both param driven (metrics[include_audience_attention]=1) and route drive (v4/metrics/attention) attention

 

                    "view_completion": {

                        "data": {

                            "rate": "97.6876639400",

                            "rate_placement": "8238.0007",

                            "index": "76"

                        }

                    }

                },

 


v4.7.1 - Aug 31, 2020

Maintenance release

** Non client facing bugfixes


v4.7.0 - Aug 25, 2020

Feature release

** Improvement
    * OTT > Added Fandango ID movie filter 

New endpoint: /v4/client/ott/movies
A non-paginated list of all client OTT movies

Expanded filter: filter[fandango_id] can now be used with /metrics/*/ott endpoints


v4.6.2 - Aug 24, 2020

Maintenance release


** Bug
    * OTT Analytics> Publishers page shows incorrect "OTT Data Available Through" date
    * Airings > Local ads not returning 
    * TV Conversions > columns missing for null conversions
    * Movie Conversions > Conversion Types Not Showing in Dashboard


v4.6.1 - Aug 18, 2020

Maintenance release

** Bug
    * Bug in custom data tag occasionally causing 500 server error

** Improvement
    * Response > Meta > Include min/max page size


v4.6.0 - Aug 12, 2020

Feature release

** Improvement
    * Conversions > Added OTT conversions 

The most basic call: https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott
This will provide an ott-centric view of the conversions, with no linear overlap.
It’s not necessary to specify the OTT pixel as the API will automatically pick appropriate OTT pixel based on the provided Conversion pixel.

Bring in linear impressions: https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott?metrics[include_audience]=1
This will add linear impression data based on the conversion’s brand

Standard conversion filters can be used: https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott?filter[conversion_attribution_window]=14d&filter[conversion_type]=WEB&filter[conversion_application]=VISIT

Group by OTT publishers (linear not supported): https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott?filter[group_by]=P&metrics[include_audience]=0
Day over day: https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott?filter[group_by]=T
A number of sorts are supported: https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott?sort=-ottimpressions

A complete looking request: https://api.ispot.tv/v4/metrics/conversions/{conversion-id}/ott?page[number]=1&metrics[include_audience]=1&filter[start_date]=2020-07-14&filter[end_date]=2020-08-03&filter[airing_type]=N,R&filter[national_only]=1&filter[conversion_attribution_window]=14d&filter[conversion_type]=WEB&filter[conversion_application]=VISIT&sort=-ottimpressions

 



v4.5.0 - July 07, 2020

Feature release

** Improvement
    * TV Conversions > Media Recommendations > Update data engine 
    * Segments > Update data engine


v4.4.2 - June 30, 2020
Maintenance release

** Bug
    * Appropriately handle expired resources 
    * TVC Pixel Tracking IDs populating in OTT Analytics filter


** Task
    * Meta > Airings > Refactor underlying tables 
    * General dependency cleanup and improvements


v4.4.0 - June 25, 2020
Feature release

** Improvement
    * Digital > Update data engine 
    * Engagement > Update data engine

** Improvement
    * OTT > Linear Reach Improvements


v4.3.1 - June 18, 2020
Maintenance release

** Bug
    * OTT > Some customers Missing Tracking IDs
    * General bug fixes

** Improvement
    * Conversions > Custom data tags now support an ID
    * Opt-Out >  Add IP Address and MAID Support
    * OTT > Source Filter naming improvements


v4.3.0 - June 16, 2020
Feature release

** Improvement
    * TV Conversions > Lift > Update data engine 


v4.2.1 - June 11, 2020
Maintenance release

** Task
    * Update OAuth2 library
    * General bug fixes and improvements


v4.2.0 - June 09, 2020
Feature release

** Improvement
    * TV Conversions > Add Partner View support for Networks


v4.0.1 - May 11, 2020
Maintenance release

** Bug
    * Error messaging improvements
    * Fixed access error affecting some customers
    * Airings > Time specific query is broken

** New Feature
    * TV Conversions > Support application type renaming

** Task
    * Show > MetadataController > Series ID Regex


v4.0.0 - May 07, 2020
Official non-beta release


** Bug
    * Fixed data discrepancy observed for some accounts 
    * Fixed some account not showing expected data on global pages
    * Fixed data discrepancy (less number of industries) observed for some accounts

** Task
    * Documentation > Migration guide
    * Python SDK for API v4
    * Documentation > Add pagination section
    * Data Engine > Attention
    * Data Engine > Media Measurement
    * Data Engine > Audience