This is legacy documentation, and may not be complete. To see the latest documentation, if you are a marketer, refer to the Marketers site. If you are a measurement partner, refer to the Measurement Partners site.
Stay organized with collections
Save and categorize content based on your preferences.
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 labeladh-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:
Follow the instructions on how to create a query, ensuring that you select YouTube Reserve as the buying door and Video Viewability as the query template.
Click the Run button 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-accreditedlabel 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__importprint_functionimportjsonimportos.pathfromgoogle.auth.transport.requestsimportRequestfromgoogle.oauth2.credentialsimportCredentialsfromgoogle_auth_oauthlib.flowimportInstalledAppFlowfromgoogleapiclient.discoveryimportbuild# 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.ifos.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.ifnotcredsornotcreds.valid:ifcredsandcreds.expiredandcreds.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.withopen(TOKEN_FILE,'w')astoken: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__importprint_functionimportjsonimportos.pathfromgoogle.auth.transport.requestsimportRequestfromgoogle.oauth2.credentialsimportCredentialsfromgoogle_auth_oauthlib.flowimportInstalledAppFlowfromgoogleapiclient.discoveryimportbuild# 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.ifos.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.ifnotcredsornotcreds.valid:ifcredsandcreds.expiredandcreds.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.withopen(TOKEN_FILE,'w')astoken: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
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-09-18 UTC."],[[["\u003cp\u003eThis guide provides instructions for querying viewability and invalid traffic metrics for Google Ads, Display & Video 360, and YouTube Reserve inventory.\u003c/p\u003e\n"],["\u003cp\u003eYou can query MRC-accredited viewability metrics using the provided UI template or the ADH API.\u003c/p\u003e\n"],["\u003cp\u003eTrueView view metrics require the ADH API for querying and are distinct from standard viewability metrics.\u003c/p\u003e\n"],["\u003cp\u003eTo retrieve invalid traffic and viewability metrics using the API, utilize the \u003ccode\u003egenerateIvtReport\u003c/code\u003e and \u003ccode\u003estartAnalysis\u003c/code\u003e endpoints, respectively.\u003c/p\u003e\n"],["\u003cp\u003eFormulas are provided for calculating viewability metrics net of general invalid traffic (GIVT) to ensure accuracy.\u003c/p\u003e\n"]]],["\n\nI'm sorry, but I can't help you with this."],null,["# Query viewability and invalid traffic metrics\n\nOverview\n--------\n\nThe instructions below provide examples of how to query both valid [viewability](/ads-data-hub/glossary#viewability) traffic, and [invalid traffic](/ads-data-hub/glossary#invalid_traffic) by using the API. These metrics are limited to inventory purchased using Google Ads, Display \\& Video 360, and YouTube reserve.\n\nNote that MRC-accredited [TrueView view](/ads-data-hub/resources/glossary#trueview) 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.\n\nSelect the buying door that you want to query viewability metrics for: \nGoogle Ads Display \\& Video 360 YouTube Reserve\n\nQuery viewability metrics using the UI\n--------------------------------------\n\nThe templated viewability query provides MRC-accredited metrics.\n\nMRC accreditation is binary---your results can be accredited, or not---and applies to your entire results table. In BigQuery, the [label](https://cloud.google.com/bigquery/docs/labels-intro) `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.\n\nTo run the MRC-accredited query through the template:\n\n1. Follow the instructions on [how to create a query](/ads-data-hub/guides/run-queries), ensuring that you select **YouTube Reserve** as the buying door and **Video Viewability** as the query template.\n2. Click the **Run** button next to **Use template**.\n\n| **Note:** The order IDs should all specify the same time zone as used in the UI, otherwise the data may not be accurate for campaigns outside the specified time zone.\n\nQuery invalid traffic and viewability metrics using the API\n-----------------------------------------------------------\n\nInvalid 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](https://cloud.google.com/bigquery/docs/labels-intro) 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.\n\nFollow the setup and authorization/authentication instructions in the [API quickstart](/ads-data-hub/guides/quickstart-api).\n\nAfter 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:\n\n- Client secrets file\n- Customer ID\n- API key\n- Order IDs\n- Timezone\n\n### Sample code\n\n### Invalid traffic\n\n from __future__ import print_function\n import json\n import os.path\n from google.auth.transport.requests import Request\n from google.oauth2.credentials import Credentials\n from google_auth_oauthlib.flow import InstalledAppFlow\n from googleapiclient.discovery import build\n\n # If modifying these scopes, delete the file `token.json`.\n SCOPES = ['https://www.googleapis.com/auth/adsdatahub']\n TOKEN_FILE = 'token.json'\n\n creds = None\n\n # The file token.json stores the user's access and refresh tokens, and is\n # created automatically when the authorization flow completes for the first\n # time.\n if os.path.exists(TOKEN_FILE):\n creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)\n # If there are no (valid) credentials available, let the user log in.\n if not creds or not creds.valid:\n if creds and creds.expired and creds.refresh_token:\n creds.refresh(Request())\n else:\n flow = InstalledAppFlow.from_client_secrets_file(\n 'YOUR_CLIENT_SECRETS.json', SCOPES)\n creds = flow.run_local_server(port=0)\n # Save the credentials for the next run.\n with open(TOKEN_FILE, 'w') as token:\n token.write(creds.to_json())\n\n service = build('adsdatahub', 'v1', credentials=creds,\n developerKey='YOUR_API_KEY',\n discoveryServiceUrl='https://adsdatahub.googleapis.com/$discovery/rest?version=v1&labels=')\n\n body = {\n 'ads_data_customer_id': YOUR_CUSTOMER_ID,\n 'start_date': {\n 'year': 2019,\n 'month': 12,\n 'day': 15\n },\n 'end_date': {\n 'year': 2019,\n 'month': 12,\n 'day': 20\n },\n 'time_zone': 'YOUR_TIMEZONE',\n 'yt_reserve_dimensions': {\n 'order_ids': [YOUR_ORDER_IDS],\n 'metric_type': 'METRIC_TYPE_IMPRESSION'\n },\n 'dest_table': 'YOUR_DESTINATION_TABLE'\n }\n\n resp = service.customers().generateIvtReport(name='customers/YOUR_CUSTOMER_ID,\n body=body).execute()\n print(json.dumps(resp))\n\n### Viewability metrics\n\n from __future__ import print_function\n import json\n import os.path\n from google.auth.transport.requests import Request\n from google.oauth2.credentials import Credentials\n from google_auth_oauthlib.flow import InstalledAppFlow\n from googleapiclient.discovery import build\n\n # If modifying these scopes, delete the file `token.json`.\n SCOPES = ['https://www.googleapis.com/auth/adsdatahub']\n TOKEN_FILE = 'token.json'\n\n creds = None\n\n # The file token.json stores the user's access and refresh tokens, and is\n # created automatically when the authorization flow completes for the first\n # time.\n if os.path.exists(TOKEN_FILE):\n creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)\n # If there are no (valid) credentials available, let the user log in.\n if not creds or not creds.valid:\n if creds and creds.expired and creds.refresh_token:\n creds.refresh(Request())\n else:\n flow = InstalledAppFlow.from_client_secrets_file(\n 'YOUR_CLIENT_SECRETS.json', SCOPES)\n creds = flow.run_local_server(port=0)\n # Save the credentials for the next run.\n with open(TOKEN_FILE, 'w') as token:\n token.write(creds.to_json())\n\n service = build('adsdatahub', 'v1', credentials=creds,\n developerKey='YOUR_API_KEY',\n discoveryServiceUrl='https://adsdatahub.googleapis.com/$discovery/rest?version=v1&labels=')\n\n name = 'customers/global/analysisQueries/ad88e8562a8f4baa9c8522945fe95522'\n body = {\n 'spec': {\n 'ads_data_customer_id': YOUR_CUSTOMER_ID,\n 'start_date': {\n 'year': 2019,\n 'month': 12,\n 'day': 15\n },\n 'end_date': {\n 'year': 2019,\n 'month': 12,\n 'day': 20\n },\n 'time_zone': 'YOUR_TIMEZONE',\n 'parameter_values': {\n 'line_item_ids': {\n 'array_value': {\n 'values': [\n {\n 'value': 'YOUR_LINE_ITEM_ID'\n },\n ]\n }\n }\n }\n },\n 'dest_table': 'YOUR_DESTINATION_TABLE',\n 'customer_id': YOUR_CUSTOMER_ID\n }\n\n resp = service.customers().analysisQueries().start(name=name,body=body).execute()\n print(json.dumps(resp))\n\nCalculate viewability metrics net of general invalid traffic\n------------------------------------------------------------\n\nUse the following formulas to derive MRC-accredited viewability metrics net of\ngeneral invalid traffic (GIVT):\n\n- Total Impressions (Net of GIVT): Total Impressions - General Invalid Impressions\n- Viewable Impressions (Net of GIVT): Viewable Impressions + Invalid Viewable Impressions - GIVT Viewable Impressions\n- Measurable Impressions (Net of GIVT): Measurable Impressions + Invalid Measurable Impressions - GIVT Measurable Impressions\n- Eligible Impressions (Net of GIVT): Eligible Impressions + Invalid Eligible Impressions - GIVT Eligible Impressions\n- Non-Viewable Impression (Net of GIVT) : Measurable Impressions (Net of GIVT) - Viewable Impressions (Net of GIVT)\n- Unmeasurable Impressions (Net of GIVT): Eligible Impressions (Net of GIVT) - Measurable Impressions (Net of GIVT)\n- % Measurable Impressions (Net of GIVT): Measurable Impressions (Net of GIVT) / Eligible Impressions (Net of GIVT)\n- % Viewable Impressions (Net of GIVT): Viewable Impressions (Net of GIVT) / Measurable Impressions (Net of GIVT)"]]