Create query

The Bid Manager API Query resource represents what you see in the UI as a Display & Video 360 report. Run this query to generate a Report resource. If successful, the Report resource provides the URL where you can download the resulting report.

This page explains how to structure and create a Query resource.

Choose filters, dimensions, and metrics

In each Query , provide the following Parameters in the params field to refine the data that's returned in the report:

filters limit the scope of the data. filters takes a list of FilterPair objects, where the type is a Filter enum, and the value is an identifying string, such as the relevant resource ID.
groupBys define the dimensions for the report, represented by a list of Filter enums.
metrics define the data populating the report, represented by a list of Metric enums.

For more details on Query structure, see the reference documentation .

When choosing these values, consider your ReportType , that's set in the type field. Your selected metrics and filters values must be compatible with the report type for the report to successfully generate.

Create a query

Once you determine the core structure of your report, you can create your query.

Here's how to create an ad hoc report consisting of data from the last seven days:

Java

 // Display name of the query to create. 
 String 
  
 displayName 
  
 = 
  
  display 
 - 
 name 
 
 ; 
 // The report type. 
 String 
  
 reportType 
  
 = 
  
  report 
 - 
 type 
 
 ; 
 // The advertisers and campaigns by which to filter report data. 
 List<String 
 > 
  
 advertiserIdFilters 
  
 = 
  
 Arrays 
 . 
 asList 
 ( 
  advertiser 
 - 
 id 
 ,... 
 
); List<String 
 > 
  
 campaignIdFilters 
  
 = 
  
 Arrays 
 . 
 asList 
 ( 
  campaign 
 - 
 id 
 ,... 
 
); // The dimensions and metrics for the report. 
 List<String 
 > 
  
 dimensions 
  
 = 
  
 Arrays 
 . 
 asList 
 ( 
  dimension 
 ,... 
 
); List<String 
 > 
  
 metrics 
  
 = 
  
 Arrays 
 . 
 asList 
 ( 
  metric 
 ,... 
 
); // Build a list of filter pairs from given IDs. 
 List<FilterPair 
 > 
  
 filters 
  
 = 
  
 new 
  
 ArrayList<FilterPair 
 > 
 (); 
 if 
  
 ( 
 advertiserIdFilters 
  
 != 
  
 null 
 ) 
  
 { 
  
 for 
  
 ( 
 String 
  
 advertiserId 
  
 : 
  
 advertiserIdFilters 
 ) 
  
 { 
  
 filters 
 . 
 add 
 ( 
  
 new 
  
 FilterPair 
 (). 
 setType 
 ( 
 "FILTER_ADVERTISER" 
 ). 
 setValue 
 ( 
 advertiserId 
 )); 
  
 } 
 } 
 if 
  
 ( 
 campaignIdFilters 
  
 != 
  
 null 
 ) 
  
 { 
  
 for 
  
 ( 
 String 
  
 campaignId 
  
 : 
  
 campaignIdFilters 
 ) 
  
 { 
  
 filters 
 . 
 add 
 ( 
  
 new 
  
 FilterPair 
 (). 
 setType 
 ( 
 "FILTER_MEDIA_PLAN" 
 ). 
 setValue 
 ( 
 campaignId 
 )); 
  
 } 
 } 
 // Create the query structure. 
 Query 
  
 query 
  
 = 
  
 new 
  
 Query 
 (); 
 // Build and set the metadata object. 
 QueryMetadata 
  
 metadata 
  
 = 
  
 new 
  
 QueryMetadata 
 (); 
 metadata 
 . 
 setTitle 
 ( 
 displayName 
 ); 
 metadata 
 . 
 setDataRange 
 ( 
 new 
  
 DataRange 
 (). 
 setRange 
 ( 
 "LAST_7_DAYS" 
 )); 
 metadata 
 . 
 setFormat 
 ( 
 "CSV" 
 ); 
 query 
 . 
 setMetadata 
 ( 
 metadata 
 ); 
 // Build the parameters object. 
 Parameters 
  
 parameters 
  
 = 
  
 new 
  
 Parameters 
 (); 
 parameters 
 . 
 setType 
 ( 
 reportType 
 ); 
 parameters 
 . 
 setGroupBys 
 ( 
 dimensions 
 ); 
 parameters 
 . 
 setFilters 
 ( 
 filters 
 ); 
 parameters 
 . 
 setMetrics 
 ( 
 metrics 
 ); 
 // Set parameters object in query. 
 query 
 . 
 setParams 
 ( 
 parameters 
 ); 
 // Build and set the schedule object. 
 QuerySchedule 
  
 schedule 
  
 = 
  
 new 
  
 QuerySchedule 
 (); 
 schedule 
 . 
 setFrequency 
 ( 
 "ONE_TIME" 
 ); 
 query 
 . 
 setSchedule 
 ( 
 schedule 
 ); 
 // Create the query. 
 Query 
  
 queryResponse 
  
 = 
  
 service 
 . 
 queries 
 (). 
 create 
 ( 
 query 
 ). 
 execute 
 (); 
 // Log query creation. 
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Query %s was created.%n" 
 , 
  
 queryResponse 
 . 
 getQueryId 
 ());

Python

 # Display name of the query to create. 
 display_name 
 = 
  display 
 - 
 name 
 
 # The report type. 
 report_type 
 = 
  report 
 - 
 type 
 
 # The advertisers and campaigns by which to filter report data. 
 filtered_advertiser_ids 
 = 
 [ 
  advertiser 
 - 
 id 
 , 
 ... 
 
 ] 
 filtered_campaign_ids 
 = 
 [ 
  campaign 
 - 
 id 
 , 
 ... 
 
 ] 
 # The dimensions and metrics for the report. 
 dimensions 
 = 
 [ 
  dimension 
 , 
 ... 
 
 ] 
 metrics 
 = 
 [ 
  metric 
 , 
 ... 
 
 ] 
 # Build list of FilterPair objects. 
 filters 
 = 
 [] 
 if 
 filtered_campaign_ids 
 != 
 None 
 : 
 filters 
 . 
 extend 
 ([ 
 { 
 "type" 
 : 
 "FILTER_MEDIA_PLAN" 
 , 
 "value" 
 : 
 id 
 } 
 for 
 id 
 in 
 filtered_campaign_ids 
 ]) 
 if 
 filtered_advertiser_ids 
 != 
 None 
 : 
 filters 
 . 
 extend 
 ([ 
 { 
 "type" 
 : 
 "FILTER_ADVERTISER" 
 , 
 "value" 
 : 
 id 
 } 
 for 
 id 
 in 
 filtered_advertiser_ids 
 ]) 
 # Build query object. 
 query_obj 
 = 
 { 
 "metadata" 
 : 
 { 
 "title" 
 : 
 display_name 
 , 
 "dataRange" 
 : 
 { 
 "range" 
 : 
 "LAST_7_DAYS" 
 }, 
 "format" 
 : 
 "CSV" 
 , 
 }, 
 "params" 
 : 
 { 
 "type" 
 : 
 report_type 
 , 
 "groupBys" 
 : 
 dimensions 
 , 
 "filters" 
 : 
 filters 
 , 
 "metrics" 
 : 
 metrics 
 , 
 }, 
 "schedule" 
 : 
 { 
 "frequency" 
 : 
 "ONE_TIME" 
 } 
 } 
 # Create query object. 
 query_response 
 = 
 service 
 . 
 queries 
 () 
 . 
 create 
 ( 
 body 
 = 
 query_obj 
 ) 
 . 
 execute 
 () 
 # Print new query ID. 
 print 
 ( 
 f 
 'Query 
 { 
 query_response 
 [ 
 "queryId" 
 ] 
 } 
 was created.' 
 )

PHP

 // Display name of the query to create. 
 $displayName = display-name 
; 
 // The report type. 
 $reportType = report-type 
; 
 // Advertiser ID and campaign ID by which to filter data. 
 $advertiserIdFilters = array( advertiser-id,... 
); 
 $campaignIdFilters = array( campaign-id,... 
); 
 // The dimensions and metrics for the report. 
 $dimensions = array( dimension,... 
); 
 $metrics = array( metric,... 
); 
 // Build a list of filter pairs from given IDs. 
 $filters = array(); 
 foreach ($advertiserIdFilters as $advertiserId) { 
 $filterPair = new Google_Service_DoubleClickBidManager_FilterPair(); 
 $filterPair->setType("FILTER_ADVERTISER"); 
 $filterPair->setValue($advertiserId); 
 array_push($filters, $filterPair); 
 } 
 foreach ($campaignIdFilters as $campaignId) { 
 $filterPair = new Google_Service_DoubleClickBidManager_FilterPair(); 
 $filterPair->setType("FILTER_MEDIA_PLAN"); 
 $filterPair->setValue($campaignId); 
 array_push($filters, $filterPair); 
 } 
 // Create the query structure. 
 $query = new Google_Service_DoubleClickBidManager_Query(); 
 // Build and set the metadata object. 
 $metadata = new Google_Service_DoubleClickBidManager_QueryMetadata(); 
 $metadata->setTitle($displayName); 
 $metadata->setFormat("CSV"); 
 $dataRange = new Google_Service_DoubleClickBidManager_DataRange(); 
 $dataRange->setRange("LAST_7_DAYS"); 
 $metadata->setDataRange($dataRange); 
 $query->setMetadata($metadata); 
 // Build and set the parameters object. 
 $parameters = new Google_Service_DoubleClickBidManager_Parameters(); 
 $parameters->setType($reportType); 
 $parameters->setGroupBys($dimensions); 
 $parameters->setFilters($filters); 
 $parameters->setMetrics($metrics); 
 $query->setParams($parameters); 
 // Build and set the schedule object. 
 $schedule = new Google_Service_DoubleClickBidManager_QuerySchedule(); 
 $schedule->setFrequency("ONE_TIME"); 
 $query->setSchedule($schedule); 
 // Call the API, creating the query. 
 $queryResult = $this->service->queries->create($query); 
 printf('Query %s was created.<br>', $queryResult->getQueryId());

Overview

Run a query