Query viewability and invalid traffic metrics

    • This page explains how to query valid viewability traffic and invalid traffic using the API for inventory purchased through Google Ads, Display & Video 360, and YouTube reserve.

    • MRC-accredited TrueView view metrics require the use of the ADH API and should not be confused with viewability metrics.

    • MRC accreditation applies to your entire results table and is indicated by the adh-mrc-accredited label in BigQuery.

    • Invalid traffic and viewability metrics can be retrieved through the ADH API using the generateIvtReport and startAnalysis endpoints, respectively, to achieve MRC accreditation.

    • Formulas are provided to calculate MRC-accredited viewability metrics net of general invalid traffic.

    Overview

    The instructions below provide examples of how to query both valid viewability traffic, and invalid traffic by using the API. These metrics are limited to inventory purchased using Google Ads, Display & Video 360, and YouTube reserve.

    Note that MRC-accredited TrueView view view metrics require the use of the ADH API, as there is no associated templated query. Additionally, TrueView view view metrics shouldn't be confused with viewability metrics.

    Select the buying door that you want to query viewability metrics for:

    Query viewability metrics using the UI

    The templated viewability query provides MRC-accredited metrics.

    MRC accreditation is binary—your results can be accredited, or not—and applies to your entire results table. In BigQuery, the label adh-mrc-accredited is applied to all MRC-accredited results. You must run the query through the template in order for your metrics to be MRC-accredited.

    To run the MRC-accredited query through the template:

    1. Follow the instructions on how to create a query , ensuring that you select YouTube Reserve as the buying door and Video Viewabilityas the query template.
    2. Click the Runbutton next to Use template.

    Query invalid traffic and viewability metrics using the API

    Invalid traffic and viewability metrics can be retrieved from the ADH API using the generateIvtReport and startAnalysis endpoints. For invalid traffic, your metrics must be retrieved through the generateIvtReport in order for the adh-mrc-accredited label to be applied and your metrics to be MRC-accredited. Similarly, the global query specified below must be used for viewability metrics through the ADH API for MRC accreditation. This section covers how to send a request to this endpoint using the Python client library.

    Follow the setup and authorization/authentication instructions in the API quickstart .

    After replacing the following fields with information relevant to your account, you can run the query below to retrieve an invalid traffic report for your YouTube Reserve campaigns:

    • Client secrets file
    • Customer ID
    • API key
    • Order IDs
    • Timezone

    Sample code

    Invalid traffic

      from 
  
 __future__ 
  
 import 
 print_function 
 import 
  
 json 
 import 
  
 os.path 
 from 
  
 google.auth.transport.requests 
  
 import 
 Request 
 from 
  
 google.oauth2.credentials 
  
 import 
 Credentials 
 from 
  
 google_auth_oauthlib.flow 
  
 import 
 InstalledAppFlow 
 from 
  
 googleapiclient.discovery 
  
 import 
 build 
 # If modifying these scopes, delete the file `token.json`. 
 SCOPES 
 = 
 [ 
 'https://www.googleapis.com/auth/adsdatahub' 
 ] 
 TOKEN_FILE 
 = 
 'token.json' 
 creds 
 = 
 None 
 # The file token.json stores the user's access and refresh tokens, and is 
 # created automatically when the authorization flow completes for the first 
 # time. 
 if 
 os 
 . 
 path 
 . 
 exists 
 ( 
 TOKEN_FILE 
 ): 
 creds 
 = 
 Credentials 
 . 
 from_authorized_user_file 
 ( 
 TOKEN_FILE 
 , 
 SCOPES 
 ) 
 # If there are no (valid) credentials available, let the user log in. 
 if 
 not 
 creds 
 or 
 not 
 creds 
 . 
 valid 
 : 
 if 
 creds 
 and 
 creds 
 . 
 expired 
 and 
 creds 
 . 
 refresh_token 
 : 
 creds 
 . 
 refresh 
 ( 
 Request 
 ()) 
 else 
 : 
 flow 
 = 
 InstalledAppFlow 
 . 
 from_client_secrets_file 
 ( 
 'YOUR_CLIENT_SECRETS.json' 
 , 
 SCOPES 
 ) 
 creds 
 = 
 flow 
 . 
 run_local_server 
 ( 
 port 
 = 
 0 
 ) 
 # Save the credentials for the next run. 
 with 
 open 
 ( 
 TOKEN_FILE 
 , 
 'w' 
 ) 
 as 
 token 
 : 
 token 
 . 
 write 
 ( 
 creds 
 . 
 to_json 
 ()) 
 service 
 = 
 build 
 ( 
 'adsdatahub' 
 , 
 'v1' 
 , 
 credentials 
 = 
 creds 
 , 
 developerKey 
 = 
 'YOUR_API_KEY' 
 , 
 discoveryServiceUrl 
 = 
 'https://adsdatahub.googleapis.com/$discovery/rest?version=v1&labels=' 
 ) 
 body 
 = 
 { 
 'ads_data_customer_id' 
 : 
 YOUR_CUSTOMER_ID 
 , 
 'start_date' 
 : 
 { 
 'year' 
 : 
 2019 
 , 
 'month' 
 : 
 12 
 , 
 'day' 
 : 
 15 
 }, 
 'end_date' 
 : 
 { 
 'year' 
 : 
 2019 
 , 
 'month' 
 : 
 12 
 , 
 'day' 
 : 
 20 
 }, 
 'time_zone' 
 : 
 'YOUR_TIMEZONE' 
 , 
 'yt_reserve_dimensions' 
 : 
 { 
 'order_ids' 
 : 
 [YOUR_ORDER_IDS], 
 'metric_type' 
 : 
 'METRIC_TYPE_IMPRESSION' 
 }, 
 'dest_table' 
 : 
 'YOUR_DESTINATION_TABLE' 
 } 
 resp 
 = 
 service 
 . 
 customers 
 () 
 . 
 generateIvtReport 
 ( 
 name 
 = 
 'customers/YOUR_CUSTOMER_ID, 
 body 
 = 
 body 
 ) 
 . 
 execute 
 () 
 print 
 ( 
 json 
 . 
 dumps 
 ( 
 resp 
 ))

    Viewability metrics

      from 
  
 __future__ 
  
 import 
 print_function 
 import 
  
 json 
 import 
  
 os.path 
 from 
  
 google.auth.transport.requests 
  
 import 
 Request 
 from 
  
 google.oauth2.credentials 
  
 import 
 Credentials 
 from 
  
 google_auth_oauthlib.flow 
  
 import 
 InstalledAppFlow 
 from 
  
 googleapiclient.discovery 
  
 import 
 build 
 # If modifying these scopes, delete the file `token.json`. 
 SCOPES 
 = 
 [ 
 'https://www.googleapis.com/auth/adsdatahub' 
 ] 
 TOKEN_FILE 
 = 
 'token.json' 
 creds 
 = 
 None 
 # The file token.json stores the user's access and refresh tokens, and is 
 # created automatically when the authorization flow completes for the first 
 # time. 
 if 
 os 
 . 
 path 
 . 
 exists 
 ( 
 TOKEN_FILE 
 ): 
 creds 
 = 
 Credentials 
 . 
 from_authorized_user_file 
 ( 
 TOKEN_FILE 
 , 
 SCOPES 
 ) 
 # If there are no (valid) credentials available, let the user log in. 
 if 
 not 
 creds 
 or 
 not 
 creds 
 . 
 valid 
 : 
 if 
 creds 
 and 
 creds 
 . 
 expired 
 and 
 creds 
 . 
 refresh_token 
 : 
 creds 
 . 
 refresh 
 ( 
 Request 
 ()) 
 else 
 : 
 flow 
 = 
 InstalledAppFlow 
 . 
 from_client_secrets_file 
 ( 
 'YOUR_CLIENT_SECRETS.json' 
 , 
 SCOPES 
 ) 
 creds 
 = 
 flow 
 . 
 run_local_server 
 ( 
 port 
 = 
 0 
 ) 
 # Save the credentials for the next run. 
 with 
 open 
 ( 
 TOKEN_FILE 
 , 
 'w' 
 ) 
 as 
 token 
 : 
 token 
 . 
 write 
 ( 
 creds 
 . 
 to_json 
 ()) 
 service 
 = 
 build 
 ( 
 'adsdatahub' 
 , 
 'v1' 
 , 
 credentials 
 = 
 creds 
 , 
 developerKey 
 = 
 'YOUR_API_KEY' 
 , 
 discoveryServiceUrl 
 = 
 'https://adsdatahub.googleapis.com/$discovery/rest?version=v1&labels=' 
 ) 
 name 
 = 
 'customers/global/analysisQueries/ad88e8562a8f4baa9c8522945fe95522' 
 body 
 = 
 { 
 'spec' 
 : 
 { 
 'ads_data_customer_id' 
 : 
 YOUR_CUSTOMER_ID 
 , 
 'start_date' 
 : 
 { 
 'year' 
 : 
 2019 
 , 
 'month' 
 : 
 12 
 , 
 'day' 
 : 
 15 
 }, 
 'end_date' 
 : 
 { 
 'year' 
 : 
 2019 
 , 
 'month' 
 : 
 12 
 , 
 'day' 
 : 
 20 
 }, 
 'time_zone' 
 : 
 'YOUR_TIMEZONE' 
 , 
 'parameter_values' 
 : 
 { 
 'line_item_ids' 
 : 
 { 
 'array_value' 
 : 
 { 
 'values' 
 : 
 [ 
 { 
 'value' 
 : 
 'YOUR_LINE_ITEM_ID' 
 }, 
 ] 
 } 
 } 
 } 
 }, 
 'dest_table' 
 : 
 'YOUR_DESTINATION_TABLE' 
 , 
 'customer_id' 
 : 
 YOUR_CUSTOMER_ID 
 } 
 resp 
 = 
 service 
 . 
 customers 
 () 
 . 
 analysisQueries 
 () 
 . 
 start 
 ( 
 name 
 = 
 name 
 , 
 body 
 = 
 body 
 ) 
 . 
 execute 
 () 
 print 
 ( 
 json 
 . 
 dumps 
 ( 
 resp 
 ))

    Calculate viewability metrics net of general invalid traffic

    Use the following formulas to derive MRC-accredited viewability metrics net of general invalid traffic (GIVT):

    • Total Impressions (Net of GIVT): Total Impressions - General Invalid Impressions
    • Viewable Impressions (Net of GIVT): Viewable Impressions + Invalid Viewable Impressions - GIVT Viewable Impressions
    • Measurable Impressions (Net of GIVT): Measurable Impressions + Invalid Measurable Impressions - GIVT Measurable Impressions
    • Eligible Impressions (Net of GIVT): Eligible Impressions + Invalid Eligible Impressions - GIVT Eligible Impressions
    • Non-Viewable Impression (Net of GIVT) : Measurable Impressions (Net of GIVT) - Viewable Impressions (Net of GIVT)
    • Unmeasurable Impressions (Net of GIVT): Eligible Impressions (Net of GIVT) - Measurable Impressions (Net of GIVT)
    • % Measurable Impressions (Net of GIVT): Measurable Impressions (Net of GIVT) / Eligible Impressions (Net of GIVT)
    • % Viewable Impressions (Net of GIVT): Viewable Impressions (Net of GIVT) / Measurable Impressions (Net of GIVT)
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: