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 explains how to query viewability and invalid traffic data for Google Ads, Display & Video 360, and YouTube Reserve inventory via the Ads Data Hub (ADH) API.\u003c/p\u003e\n"],["\u003cp\u003eMRC-accredited viewability metrics are available through a templated query in the UI or a specific global query via the API.\u003c/p\u003e\n"],["\u003cp\u003eThe API can be used to retrieve invalid traffic and viewability metrics, with dedicated endpoints and sample code provided for both.\u003c/p\u003e\n"],["\u003cp\u003eTo derive viewability metrics net of general invalid traffic (GIVT), specific calculations combining various impression metrics are necessary.\u003c/p\u003e\n"],["\u003cp\u003eTrueView view metrics require using the ADH API and should not be confused with standard viewability metrics.\u003c/p\u003e\n"]]],["To query viewability and invalid traffic metrics, use the ADH API or UI templates. API queries use `generateIvtReport` for invalid traffic and `startAnalysis` for viewability, with specific code examples provided. Ensure MRC accreditation by using the correct API endpoints or the template, marked with the `adh-mrc-accredited` label. To calculate metrics net of invalid traffic, formulas for impressions, viewability, and measurability are included, to achieve accurate data.\n"],null,["Overview\n\nThe instructions below provide examples of how to query both valid [viewability](/ads-data-hub/marketers/glossary#viewability) traffic, and [invalid traffic](/ads-data-hub/marketers/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/marketers/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\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/marketers/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\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/marketers/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\nSample code \n\nInvalid 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\nViewability 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\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)"]]