To discuss and provide feedback on our products, join the official Display & Video 360 API and Structured Data Files Discord channel in the Google Advertising and Measurement Community server.

Assign targeting

A line item inherits the targeting assigned to its parent partner and advertiser.

Assign further targeting to a line item to focus on buying useful impressions.

Find available targeting options

Targeting is identified based on its type. Identify targeting options using one of the following ways:

Use a relevant enum value, such as with enum types AgeRange or Exchange .
Retrieve targetable entities, such as channels or location lists , using the related service.
Retrieve targeting option IDs for a targeting type using list and search methods.

How to retrieve existing targeting

Existing targeting restricts what targeting can be added to a line item. Retrieve the existing targeting for a line item across targeting types using a bulk list request.

Here's how to get the existing targeting for a line item:

Java

 // Provide the ID of the parent advertiser. 
 long 
  
 advertiserId 
  
 = 
  
  advertiser 
 - 
 id 
 
 ; 
 // Provide the ID of the line item. 
 long 
  
 lineItemId 
  
 = 
  
  line 
 - 
 item 
 - 
 id 
 
 ; 
 // Configure the list request. 
 LineItems 
 . 
 BulkListAssignedTargetingOptions 
  
 request 
  
 = 
  
 service 
  
 . 
 advertisers 
 () 
  
 . 
 lineItems 
 () 
  
 . 
 bulkListAssignedTargetingOptions 
 ( 
 advertiserId 
 ) 
  
 . 
 setLineItemIds 
 ( 
 Arrays 
 . 
 asList 
 ( 
 lineItemId 
 )); 
 // Create the response and nextPageToken variables. 
 BulkListAssignedTargetingOptionsResponse 
  
 response 
 ; 
 String 
  
 nextPageToken 
  
 = 
  
 null 
 ; 
 do 
  
 { 
  
 // Create and execute the list request. 
  
 response 
  
 = 
  
 request 
 . 
 setPageToken 
 ( 
 nextPageToken 
 ). 
 execute 
 (); 
  
 // Check if response is empty. 
  
 if 
  
 ( 
 response 
 . 
 isEmpty 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "No targeting is currently assigned to '%s'" 
 , 
  
 lineItemId 
 ); 
  
 break 
 ; 
  
 } 
  
 // Iterate over retrieved assigned targeting options. 
  
 for 
  
 ( 
 LineItemAssignedTargetingOption 
  
 liAssignedOption 
  
 : 
  
 response 
 . 
 getLineItemAssignedTargetingOptions 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Assigned Targeting Option %s found.%n" 
 , 
  
 liAssignedOption 
 . 
 getAssignedTargetingOption 
 (). 
 getName 
 ()); 
  
 } 
  
 // Update the next page token. 
  
 nextPageToken 
  
 = 
  
 response 
 . 
 getNextPageToken 
 (); 
 } 
  
 while 
  
 ( 
 ! 
 Strings 
 . 
 isNullOrEmpty 
 ( 
 nextPageToken 
 ));

Python

 # Provide the ID of the parent advertiser. 
 advertiser_id 
 = 
  advertiser 
 - 
 id 
 
 # Provide the ID of the line item. 
 line_item_id 
 = 
  line 
 - 
 item 
 - 
 id 
 
 # Create the page token variable. 
 next_page_token 
 = 
 "" 
 while 
 True 
 : 
 # Execute the list request. 
 response 
 = 
 ( 
 service 
 . 
 advertisers 
 () 
 . 
 lineItems 
 () 
 . 
 bulkListAssignedTargetingOptions 
 ( 
 advertiserId 
 = 
 advertiser_id 
 , 
 lineItemIds 
 = 
 [ 
 line_item_id 
 ], 
 pageToken 
 = 
 next_page_token 
 , 
 ) 
 . 
 execute 
 () 
 ) 
 # If response is not empty, display the retrieved assigned targeting 
 # options line items. 
 if 
 response 
 : 
 for 
 assigned_option 
 in 
 response 
 . 
 get 
 ( 
 "lineItemAssignedTargetingOptions" 
 , 
 [] 
 ): 
 ato_name 
 = 
 assigned_option 
 . 
 get 
 ( 
 "assignedTargetingOption" 
 , 
 {}) 
 . 
 get 
 ( 
 "name" 
 , 
 None 
 ) 
 if 
 ato_name 
 : 
 print 
 ( 
 f 
 "Assigned Targeting Option 
 { 
 ato_name 
 } 
 found." 
 ) 
 else 
 : 
 print 
 ( 
 f 
 "No targeting is currently assigned to 
 { 
 line_item_id 
 } 
 ." 
 ) 
 sys 
 . 
 exit 
 ( 
 1 
 ) 
 # Update the next page token. 
 # Break out of loop if there is no next page. 
 if 
 "nextPageToken" 
 in 
 response 
 : 
 next_page_token 
 = 
 response 
 [ 
 "nextPageToken" 
 ] 
 else 
 : 
 break

PHP

 // Provide the ID of the parent advertiser. 
 $advertiserId = advertiser-id 
; 
 // Provide the ID of the line item. 
 $lineItemId = line-item-id 
; 
 $retrievedLineItemTargeting = array(); 
 $response = null; 
 $nextPageToken = null; 
 do { 
 $optParams = array( 
 'lineItemIds' => array($lineItemId), 
 'filter' => $filter, 
 'pageToken' => $nextPageToken 
 ); 
 // Call the API, getting all the assigned targeting options for the 
 // identified line item. 
 try { 
 $response = $this 
 ->service 
 ->advertisers_lineItems 
 ->bulkListAssignedTargetingOptions( 
 $advertiserId, 
 $optParams 
 ); 
 } catch (\Exception $e) { 
 $this->renderError($e); 
 return; 
 } 
 if (!empty($response->getLineItemAssignedTargetingOptions())) { 
 $retrievedLineItemTargeting = array_merge($retrievedLineItemTargeting,$response->getLineItemAssignedTargetingOptions()); 
 } 
 // Update the next page token. 
 $nextPageToken = $response->getNextPageToken(); 
 } while ( 
 !empty($response->getLineItemAssignedTargetingOptions()) 
 && !empty($nextPageToken) 
 ); 
 // Print information returned by the bulk list request. 
 if (!empty($retrievedLineItemTargeting)) { 
 printf("<p>The following targeting was retrieved for line item ID %s:</p><ul>", $lineItemId); 
 foreach ($retrievedLineItemTargeting as $assignedTargetingOption) { 
 printf( 
 "<li>Assigned Targeting Option %s found.</li>", 
 $assignedTargetingOption->getAssignedTargetingOption()->getName()); 
 } 
 print("</ul>"); 
 } else { 
 printf("<p>No targeting is currently assigned to '%s'</p>", $lineItemId); 
 }

How to assign targeting

Update the targeting for line items across targeting types using bulk edit request.

Here's how to add the following targeting logic to a new line item:

Only bid on in-browser and optimized ad inventory.
Don't serve on any sites or apps in the provided channels.
Only serve ads to devices in provided geographic regions.

Java

 // Provide the ID of the parent advertiser. 
 long 
  
 advertiserId 
  
 = 
  
  advertiser 
 - 
 id 
 
 ; 
 // Provide the ID of the line item. 
 long 
  
 lineItemId 
  
 = 
  
  line 
 - 
 item 
 - 
 id 
 
 ; 
 // Provide the list of Channel resource IDs to negatively target. 
 // These can be retrieved using advertisers.channels.list. 
 List<String 
 > 
  
 negativeChannelIds 
  
 = 
  
  negative 
 - 
 channel 
 - 
 ids 
 
 ; 
 // Provide the list of Targeting Option IDs of the geographic regions to 
 // target. 
 // These can be retrieved using targetingTypes.targetingOptions.search. 
 List<String 
 > 
  
 regionIds 
  
 = 
  
  region 
 - 
 ids 
 
 ; 
 // Create list of assigned targeting options to create. 
 List<CreateAssignedTargetingOptionsRequest 
 > 
  
 createRequests 
  
 = 
  
 new 
  
 ArrayList 
< > 
 (); 
 // Build and add the web-optimized environment assigned targeting option. 
 AssignedTargetingOption 
  
 environmentAssignedTargetingOption 
  
 = 
  
 new 
  
 AssignedTargetingOption 
 () 
  
 . 
 setEnvironmentDetails 
 ( 
  
 new 
  
 EnvironmentAssignedTargetingOptionDetails 
 () 
  
 . 
 setEnvironment 
 ( 
 "ENVIRONMENT_WEB_OPTIMIZED" 
 )); 
 createRequests 
 . 
 add 
 ( 
  
 new 
  
 CreateAssignedTargetingOptionsRequest 
 () 
  
 . 
 setTargetingType 
 ( 
 "TARGETING_TYPE_ENVIRONMENT" 
 ) 
  
 . 
 setAssignedTargetingOptions 
 ( 
 Arrays 
 . 
 asList 
 ( 
 environmentAssignedTargetingOption 
 ))); 
 // Build and add list of negative channel assigned targeting options. 
 List<AssignedTargetingOption 
 > 
  
 negativeChannelAssignedTargetingOptions 
  
 = 
  
 new 
  
 ArrayList 
< > 
 (); 
 for 
  
 ( 
 String 
  
 negativeChannelId 
  
 : 
  
 negativeChannelIds 
 ) 
  
 { 
  
 negativeChannelAssignedTargetingOptions 
 . 
 add 
 ( 
  
 new 
  
 AssignedTargetingOption 
 () 
  
 . 
 setChannelDetails 
 ( 
  
 new 
  
 ChannelAssignedTargetingOptionDetails 
 () 
  
 . 
 setNegative 
 ( 
 true 
 ) 
  
 . 
 setChannelId 
 ( 
 Long 
 . 
 parseLong 
 ( 
 negativeChannelId 
 )))); 
 } 
 createRequests 
 . 
 add 
 ( 
  
 new 
  
 CreateAssignedTargetingOptionsRequest 
 () 
  
 . 
 setTargetingType 
 ( 
 "TARGETING_TYPE_CHANNEL" 
 ) 
  
 . 
 setAssignedTargetingOptions 
 ( 
 negativeChannelAssignedTargetingOptions 
 )); 
 // Build and add list of geographic assigned targeting options. 
 List<AssignedTargetingOption 
 > 
  
 geoRegionAssignedTargetingOptions 
  
 = 
  
 new 
  
 ArrayList 
< > 
 (); 
 for 
  
 ( 
 String 
  
 regionId 
  
 : 
  
 regionIds 
 ) 
  
 { 
  
 geoRegionAssignedTargetingOptions 
 . 
 add 
 ( 
  
 new 
  
 AssignedTargetingOption 
 () 
  
 . 
 setGeoRegionDetails 
 ( 
  
 new 
  
 GeoRegionAssignedTargetingOptionDetails 
 (). 
 setTargetingOptionId 
 ( 
 regionId 
 ))); 
 } 
 createRequests 
 . 
 add 
 ( 
  
 new 
  
 CreateAssignedTargetingOptionsRequest 
 () 
  
 . 
 setTargetingType 
 ( 
 "TARGETING_TYPE_GEO_REGION" 
 ) 
  
 . 
 setAssignedTargetingOptions 
 ( 
 geoRegionAssignedTargetingOptions 
 )); 
 // Create a bulk edit request. 
 BulkEditAssignedTargetingOptionsRequest 
  
 bulkEditTargetingRequest 
  
 = 
  
 new 
  
 BulkEditAssignedTargetingOptionsRequest 
 () 
  
 . 
 setLineItemIds 
 ( 
 Arrays 
 . 
 asList 
 ( 
 lineItemId 
 )) 
  
 . 
 setCreateRequests 
 ( 
 createRequests 
 ); 
 // Configure the bulk edit request. 
 BulkEditAssignedTargetingOptionsResponse 
  
 response 
  
 = 
  
 service 
  
 . 
 advertisers 
 () 
  
 . 
 lineItems 
 () 
  
 . 
 bulkEditAssignedTargetingOptions 
 ( 
 advertiserId 
 , 
  
 bulkEditTargetingRequest 
 ) 
  
 . 
 execute 
 (); 
 // Display API response information. 
 if 
  
 ( 
 response 
 . 
 getUpdatedLineItemIds 
 () 
  
 != 
  
 null 
  
 && 
  
 ! 
 response 
 . 
 getUpdatedLineItemIds 
 (). 
 isEmpty 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Targeting configurations for %s were successfully updated.%n" 
 , 
  
 response 
 . 
 getUpdatedLineItemIds 
 (). 
 get 
 ( 
 0 
 )); 
 } 
 if 
  
 ( 
 response 
 . 
 getFailedLineItemIds 
 () 
  
 != 
  
 null 
  
 && 
  
 ! 
 response 
 . 
 getFailedLineItemIds 
 (). 
 isEmpty 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
  
 "Targeting configurations for %s failed to update.%n" 
 , 
  
 response 
 . 
 getFailedLineItemIds 
 (). 
 get 
 ( 
 0 
 )); 
 } 
 if 
  
 ( 
 response 
 . 
 getErrors 
 () 
  
 != 
  
 null 
  
 && 
  
 ! 
 response 
 . 
 getErrors 
 (). 
 isEmpty 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "The failed updates were caused by the following errors:" 
 ); 
  
 for 
  
 ( 
 Status 
  
 error 
  
 : 
  
 response 
 . 
 getErrors 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Code %s: %s%n" 
 , 
  
 error 
 . 
 getCode 
 (), 
  
 error 
 . 
 getMessage 
 ()); 
  
 } 
 } 
  
 else 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "No successful or failed updates were reported." 
 ); 
 }

Python

 # Provide the ID of the parent advertiser. 
 advertiser_id 
 = 
  advertiser 
 - 
 id 
 
 # Provide the ID of the line item. 
 line_item_id 
 = 
  line 
 - 
 item 
 - 
 id 
 
 # Provide the list of Channel resource IDs to negatively target. 
 # These can be retrieved using advertisers.channels.list. 
 negative_channel_ids 
 = 
  negative 
 - 
 channel 
 - 
 ids 
 
 # Provide the list of Targeting Option IDs of the geographic regions to target. 
 # These can be retrieved using targetingTypes.targetingOptions.search. 
 region_ids 
 = 
  region 
 - 
 ids 
 
 # Build the web-optimized environment assigned targeting option. 
 environment_assigned_targeting_option 
 = 
 { 
 "environmentDetails" 
 : 
 { 
 "environment" 
 : 
 "ENVIRONMENT_WEB_OPTIMIZED" 
 } 
 } 
 # Build the negative Channel assigned targeting options. 
 negative_channel_assigned_targeting_options 
 = 
 [] 
 for 
 id 
 in 
 negative_channel_ids 
 : 
 negative_channel_assigned_targeting_options 
 . 
 append 
 ( 
 { 
 "channelDetails" 
 : 
 { 
 "channelId" 
 : 
 id 
 , 
 "negative" 
 : 
 True 
 }} 
 ) 
 # Build the geographic region assigned targeting options. 
 geographic_assigned_targeting_options 
 = 
 [] 
 for 
 id 
 in 
 region_ids 
 : 
 geographic_assigned_targeting_options 
 . 
 append 
 ( 
 { 
 "geoRegionDetails" 
 : 
 { 
 "targetingOptionId" 
 : 
 id 
 }} 
 ) 
 # Create a bulk edit request. 
 bulk_edit_targeting_request 
 = 
 { 
 "lineItemIds" 
 : 
 [ 
 line_item_id 
 ], 
 "createRequests" 
 : 
 [ 
 { 
 "targetingType" 
 : 
 "TARGETING_TYPE_ENVIRONMENT" 
 , 
 "assignedTargetingOptions" 
 : 
 [ 
 environment_assigned_targeting_option 
 ], 
 }, 
 { 
 "targetingType" 
 : 
 "TARGETING_TYPE_CHANNEL" 
 , 
 "assignedTargetingOptions" 
 : 
 ( 
 negative_channel_assigned_targeting_options 
 ), 
 }, 
 { 
 "targetingType" 
 : 
 "TARGETING_TYPE_GEO_REGION" 
 , 
 "assignedTargetingOptions" 
 : 
 geographic_assigned_targeting_options 
 , 
 }, 
 ], 
 } 
 # Build and execute request. 
 response 
 = 
 ( 
 service 
 . 
 advertisers 
 () 
 . 
 lineItems 
 () 
 . 
 bulkEditAssignedTargetingOptions 
 ( 
 advertiserId 
 = 
 advertiser_id 
 , 
 body 
 = 
 bulk_edit_targeting_request 
 ) 
 . 
 execute 
 () 
 ) 
 # Print the request results. 
 if 
 ( 
 "updatedLineItemIds" 
 in 
 response 
 and 
 len 
 ( 
 response 
 [ 
 "updatedLineItemIds" 
 ]) 
 != 
 0 
 ): 
 print 
 ( 
 f 
 'Targeting configurations for 
 { 
 response 
 [ 
 "updatedLineItemIds" 
 ][ 
 0 
 ] 
 } 
 ' 
 "were successfully updated." 
 ) 
 elif 
 ( 
 "failedLineItemIds" 
 in 
 response 
 and 
 len 
 ( 
 response 
 [ 
 "failedLineItemIds" 
 ]) 
 != 
 0 
 ): 
 print 
 ( 
 f 
 'Targeting configurations for 
 { 
 response 
 [ 
 "failedLineItemIds" 
 ][ 
 0 
 ] 
 } 
 ' 
 "failed to update." 
 ) 
 if 
 "errors" 
 in 
 response 
 and 
 len 
 ( 
 response 
 [ 
 "errors" 
 ]) 
 != 
 0 
 : 
 print 
 ( 
 "The failed updates were caused by the following errors:" 
 ) 
 for 
 error 
 in 
 response 
 [ 
 "errors" 
 ]: 
 print 
 ( 
 f 
 'Code 
 { 
 error 
 [ 
 "code" 
 ] 
 } 
 : 
 { 
 error 
 [ 
 "message" 
 ] 
 } 
 ' 
 ) 
 else 
 : 
 print 
 ( 
 "No successful or failed updates were reported." 
 )

PHP

 // Provide the ID of the parent advertiser. 
 $advertiserId = advertiser-id 
; 
 // Provide the ID of the line item. 
 $lineItemId = line-item-id 
; 
 // Provide the list of Channel resource IDs to negatively target. 
 // These can be retrieved using advertisers.channels.list. 
 $negativeChannelIds = negative-channel-ids 
; 
 // Provide the list of Targeting Option IDs of the geographic regions to 
 // target. 
 // These can be retrieved using targetingTypes.targetingOptions.search. 
 $regionIds = region-ids 
; 
 // Create list of assigned targeting options to create. 
 $createRequests = array(); 
 // Build environment assigned targeting option and add to create 
 // requests. 
 $environmentDetails = new Google_Service_DisplayVideo_EnvironmentAssignedTargetingOptionDetails(); 
 $environmentDetails->setEnvironment('ENVIRONMENT_WEB_OPTIMIZED'); 
 $environmentAssignedTargetingOption = new Google_Service_DisplayVideo_AssignedTargetingOption(); 
 $environmentAssignedTargetingOption->setEnvironmentDetails($environmentDetails); 
 $createEnvironmentAssignedTargetingOption = new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest(); 
 $createEnvironmentAssignedTargetingOption->setTargetingType('TARGETING_TYPE_ENVIRONMENT'); 
 $createEnvironmentAssignedTargetingOption->setAssignedTargetingOptions(array($environmentAssignedTargetingOption)); 
 $createRequests[] = $createEnvironmentAssignedTargetingOption; 
 // Build negative channel assigned targeting options and add to create 
 // requests. 
 $channelAssignedTargetingOptions = array(); 
 foreach ($negativeChannelIds as $channelId) { 
 $channelDetails = new Google_Service_DisplayVideo_ChannelAssignedTargetingOptionDetails(); 
 $channelDetails->setChannelId($channelId); 
 $channelDetails->setNegative(true); 
 $channelAssignedTargetingOption = new Google_Service_DisplayVideo_AssignedTargetingOption(); 
 $channelAssignedTargetingOption->setChannelDetails($channelDetails); 
 $channelAssignedTargetingOptions[] = $channelAssignedTargetingOption; 
 } 
 $createChannelAssignedTargetingOption = new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest(); 
 $createChannelAssignedTargetingOption->setTargetingType('TARGETING_TYPE_CHANNEL'); 
 $createChannelAssignedTargetingOption->setAssignedTargetingOptions($channelAssignedTargetingOptions); 
 $createRequests[] = $createChannelAssignedTargetingOption; 
 // Build region assigned targeting options and add to create requests. 
 $regionAssignedTargetingOptions = array(); 
 foreach ($regionIds as $regionId) { 
 $regionDetails = new Google_Service_DisplayVideo_GeoRegionAssignedTargetingOptionDetails(); 
 $regionDetails->setTargetingOptionId($regionId); 
 $regionAssignedTargetingOption = new Google_Service_DisplayVideo_AssignedTargetingOption(); 
 $regionAssignedTargetingOption->setGeoRegionDetails($regionDetails); 
 $regionAssignedTargetingOptions[] = $regionAssignedTargetingOption; 
 } 
 $createRegionAssignedTargetingOption = new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest(); 
 $createRegionAssignedTargetingOption->setTargetingType('TARGETING_TYPE_GEO_REGION'); 
 $createRegionAssignedTargetingOption->setAssignedTargetingOptions($regionAssignedTargetingOptions); 
 $createRequests[] = $createRegionAssignedTargetingOption; 
 $body = 
 new Google_Service_DisplayVideo_BulkEditAssignedTargetingOptionsRequest(); 
 $body->setLineItemIds(array($lineItemId)); 
 $body->setCreateRequests($createRequests); 
 // Call the API, editing the assigned targeting options for the 
 // identified line item. 
 try { 
 $response = $this 
 ->service 
 ->advertisers_lineItems 
 ->bulkEditAssignedTargetingOptions( 
 $advertiserId, 
 $body 
 ); 
 } catch (\Exception $e) { 
 $this->renderError($e); 
 return; 
 } 
 // Print information returned by the bulk edit request. 
 // List updated line item IDs. 
 if (empty($response->getUpdatedLineItemIds())) { 
 print '<p>No line items were successfully updated.</p>'; 
 } else { 
 print '<p>The targeting of the following line item IDs were ' 
 . 'updated:</p><ul>'; 
 foreach ($response->getUpdatedLineItemIds() as $id) { 
 printf('<li>%s</li>',$id); 
 } 
 print '</ul>'; 
 } 
 // List line item IDs that failed to update. 
 if (empty($response->getFailedLineItemIds())) { 
 print '<p>No line items failed to update.</p>'; 
 } else { 
 print '<p>The targeting of the following line item IDs failed to ' 
 . 'update:</p><ul>'; 
 foreach ($response->getFailedLineItemIds() as $id) { 
 printf('<li>%s</li>',$id); 
 } 
 print '</ul>'; 
 } 
 // List the errors thrown when the targeting was updated. 
 if (empty($response->getErrors())) { 
 print '<p>No errors were thrown.</p>'; 
 } else { 
 print '<p>The following errors were thrown when attempting to ' 
 . 'update the targeting:</p><ul>'; 
 foreach ($response->getErrors() as $error) { 
 printf( 
 '<li>%s: %s</li>', 
 $error->getCode(), 
 $error->getMessage() 
 ); 
 } 
 print '</ul>'; 
 }

Create a line item

Activate the line item

Assign targeting Stay organized with collections Save and categorize content based on your preferences.

Find available targeting options

How to retrieve existing targeting

Java

Python

PHP

How to assign targeting

Java

Python

PHP

Assign targeting