Set Targeting

The Targeting Options, Assigned Targeting Options, and Line items services are all used in conjunction to set line item targeting in the Display & Video 360 API. This page describes and gives examples of how to find available targeting options, assign targeting options to line items, and execute bulk operations on line items to list and edit assigned targeting options.

Find available targeting options

Targeting options use either user-specified variables, existing targetable entities, or pre-existing options to define the desired targeted audience. Using existing targetable entities and pre-existing options in targeting require entity IDs and targeting option IDs, respectively. These can be found using the Display & Video 360 API.

Listing targetable entities

In order to target a line item using an existing targetable entity, you need the ID of that entity. Targetable entities, such as channels, combined audiences, and inventory source groups, are retrievable through their own services in the Display & Video 360 API.

Each service has its own GET and LIST methods. Use the GET method to confirm that an entity is available under a given advertiser. Use the LIST method to discover all entities of that resource type that are available to a given advertiser and, therefore, able to be used in assigning targeting to a line item under that advertiser.

A subset of targetable entities can also be managed through the API. This is done through the CREATE and PATCH methods in the corresponding service, as well as services for the individual values listed in the entities, such as inventory sources, negative keywords, and locations.

Listing targeting option IDs

Targeting types that use pre-existing options are assigned using corresponding targeting option IDs.

For example, there are a finite number of household income brackets that can be targeted using targeting type TARGETING_TYPE_HOUSEHOLD_INCOME. Household income brackets are represented by an enumeration, each of which have a corresponding targeting option ID.

These targeting option IDs can be retrieved through the Targeting Options service. The targeting options service provides both GET and LIST methods. Use the GET method to retrieve the details of a targeting option identified by a targeting type and targeting option ID. Use the LIST method to list all available targeting options of a given targeting type.

The following code is an example of how to retrieve a list of possible targeting options for targeting type TARGETING_TYPE_BROWSER:

Java

// Configure the list request.
TargetingOptions.List request =
   service
       .targetingTypes()
       .targetingOptions()
       .list("TARGETING_TYPE_BROWSER")
       .setAdvertiserId(advertiser-id);

// Create the response and nextPageToken variables.
ListTargetingOptionsResponse response;
String nextPageToken = null;

do {
 // Create and execute the list request.
 response = request.setPageToken(nextPageToken).execute();

 // Check if the response is empty.
 if (response.isEmpty()) {
   System.out.print("List request returned no Targeting Options");
   break;
 }

 // Iterate over retrieved targeting options.
 for (TargetingOption option : response.getTargetingOptions()) {
   System.out.printf(
       "Targeting Option ID: %s, Browser Display Name: '%s'\n",
       option.getTargetingOptionId(), option.getBrowserDetails().getDisplayName());
 }

 // Update the next page token.
 nextPageToken = response.getNextPageToken();
} while (!Strings.isNullOrEmpty(nextPageToken));

Python

# Create the page token variable.
next_page_token = ""

while True:
# Request the targeting options list.
response = service.targetingTypes() \
  .targetingOptions().list(
    advertiserId=advertiser-id,
    targetingType="TARGETING_TYPE_BROWSER",
    pageToken=next_page_token
).execute()

# Check if response is empty.
if not response:
  print("List request returned no Targeting Options")
  break

# Iterate over retrieved targeting options.
for option in response['targetingOptions']:
  print("Targeting Option ID: %s, Browser Display Name: %s"
        % (option['targetingOptionId'], option['browserDetails']['displayName']))

# Break out of loop if there is no next page.
if 'nextPageToken' not in response:
  break

# Update the next page token.
next_page_token = response['nextPageToken']

Assign a targeting option

Targeting assigned to a line item is represented as an Assigned Targeting Option. You can manage these entities using the Assigned Targeting Options service. Creating an assigned targeting option applies those targeting details to the parent line item. Deleting an existing assigned targeting option removes that targeting.

Use the CREATE method to create assigned targeting options. Specify the targeting parameters in the details field of the assigned targeting option resource that corresponds to its intended targeting type.

The following code is an example of how to create an assigned targeting option of targeting type TARGETING_TYPE_BROWSER:

Java

    // Create an AssignedTargetingOption object of the browser targeting type.
AssignedTargetingOption assignedTargetingOption =
   new AssignedTargetingOption()
       .setBrowserDetails(
           new BrowserAssignedTargetingOptionDetails()
               .setTargetingOptionId(targeting-option-id));

// Configure the create request.
AssignedTargetingOptions.Create request =
   service
       .advertisers()
       .lineItems()
       .targetingTypes()
       .assignedTargetingOptions()
       .create(
           advertiser-id,
           line-item-id,
           "TARGETING_TYPE_BROWSER",
           assignedTargetingOption);

// Send the request.
AssignedTargetingOption response = request.execute();

// Display the new assigned targeting option.
System.out.printf("AssignedTargetingOption %s was created.",
   response.getName());

Python

# Create a assigned targeting option object.
assigned_targeting_option_obj = {
  'browserDetails': {
      'targetingOptionId': targeting-option-id
  }
}

# Create the assigned targeting option.
assigned_targeting_option = service.advertisers().lineItems()\
.targetingTypes().assignedTargetingOptions().create(
  advertiserId=advertiser-id,
  lineItemId=line-item-id,
  targetingType="TARGETING_TYPE_BROWSER",
  body=assigned_targeting_option_obj
).execute()

# Display the new assigned targeting option.
print("Assigned Targeting Option %s was created."
    % assigned_targeting_option["name"])

Targeting errors

There are a number of intricate rules regarding targeting in Display & Video 360. These are enforced in the Display & Video 360 API through errors returned on assigned targeting option creation. The error returned by the API will specify the violation.

Errors are mostly caused by existing targeting assigned to a line item. Use the Assigned Targeting Options LIST method to retrieve all targeting options of a given targeting type assigned to a line item, assess whether the desired targeting is possible given the limitations, and use the DELETE method to remove any unwanted targeting before again attempting to create the desired assigned targeting option.

Bulk targeting operations

If you want a complete view of a line item’s current targeting, want to apply a pre-set targeting configuration to a line item, or need to make multiple changes to the targeting of a line item simultaneously, consider using bulk targeting operations. The Line Items service provides two bulk methods: bulkListLineItemAssignedTargetingOptionsbulk_list and bulkEditLineItemAssignedTargetingOptions.

Listing targeting in bulk

The bulkListLineItemAssignedTargetingOptions method provides a way to look at all targeting assigned to a single line item across varying targeting types. It operates similarly to any other LIST method. You can filter the results using the filter query parameter by targeting type or inheritance.

The following code is an example of how to list all targeting options assigned to a line item that are inherited by the parent partner or advertiser:

Java

// Configure the bulk list request.
LineItems.BulkListLineItemAssignedTargetingOptions request =
   service.advertisers().lineItems()
       .bulkListLineItemAssignedTargetingOptions(advertiser-id, line-item-id);

// Set filter to only return inherited assigned targeting options.
request.setFilter(
   "inheritance=\"INHERITED_FROM_ADVERTISER\" OR inheritance=\"INHERITED_FROM_PARTNER\"");

// Create the response and nextPageToken variables.
BulkListLineItemAssignedTargetingOptionsResponse response;
String nextPageToken = null;

do {
 // Set page token and execute the list request.
 response = request.setPageToken(nextPageToken).execute();

 // Check if the response is empty.
 if (response.isEmpty()) {
   System.out.print("Bulk list request returned no Assigned Targeting Options");
   break;
 }

 // Iterate over retrieved assigned targeting options.
 for (AssignedTargetingOption assignedOption
     : response.getAssignedTargetingOptions()) {
   System.out.printf(
       "Assigned Targeting Option %s found\n",
       assignedOption.getName());
 }

 // Update the next page token.
 nextPageToken = response.getNextPageToken();
} while (!Strings.isNullOrEmpty(nextPageToken));

Python

# Create the page token variable.
next_page_token = ""

while True:
# Execute the list request.
response = service.advertisers().lineItems() \
  .bulkListLineItemAssignedTargetingOptions(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    filter="inheritance=\"NOT_INHERITED\" OR "
           "inheritance=\"INHERITED_FROM_PARTNER\"",
    pageToken=next_page_token
).execute()

# Check if response is empty.
if not response:
  print("Bulk list request returned no Assigned Targeting Options")
  break

# Iterate over retrieved assigned targeting options.
for assignedOption in response['assignedTargetingOptions']:
  print("Assigned Targeting Option %s found"
        % (assignedOption['name']))

# Break out of loop if there is no next page.
if 'nextPageToken' not in response:
  break

# Update the next page token.
next_page_token = response['nextPageToken']

Editing targeting in bulk

The bulkEditLineItemAssignedTargetingOptions method provides a way to add and remove multiple targeting options of various targeting types from a single line item simultaneously.

The method takes two lists, one of deleteAssignedTargetingOptionsRequests and one of createAssignedTargetingOptionsRequests. A single request object can represent the deletion or creation of multiple assigned targeting options of the same targeting type.

If the attempted deletion or creation of an assigned targeting option causes an error, the whole bulk action is abandoned and an error is returned. If setting identical targeting to multiple line items using multiple bulk edit requests, make sure to first confirm that the desired assignment of targeting options is valid on a single line item.

The following code is an example of how to bulk edit assigned targeting options given lists of assigned targeting options to delete and targeting options to create:

Java

// Create a bulk edit request.
BulkEditLineItemAssignedTargetingOptionsRequest requestContent =
   new BulkEditLineItemAssignedTargetingOptionsRequest();

// Build delete request list.
ArrayList<DeleteAssignedTargetingOptionsRequest>; deleteRequests =
   new ArrayList<DeleteAssignedTargetingOptionsRequest>();

// Add browser assigned targeting option IDs to delete request list.
deleteRequests.add(new DeleteAssignedTargetingOptionsRequest()
   .setTargetingType("TARGETING_TYPE_BROWSER")
   .setAssignedTargetingOptionIds(delete-browser-assigned-targeting-ids));

// Add age range assigned targeting option IDs to delete request list.
deleteRequests.add(new DeleteAssignedTargetingOptionsRequest()
   .setTargetingType("TARGETING_TYPE_AGE_RANGE")
   .setAssignedTargetingOptionIds(delete-age-assigned-targeting-ids));

// Set delete requests in edit request.
requestContent.setDeleteRequests(deleteRequests);

// Build create request list.
ArrayList<CreateAssignedTargetingOptionsRequest> createRequests =
   new ArrayList<CreateAssignedTargetingOptionsRequest>();

// Create browser assigned targeting option create request.
CreateAssignedTargetingOptionsRequest createBrowserTargetingRequest =
   new CreateAssignedTargetingOptionsRequest();
createBrowserTargetingRequest.setTargetingType("TARGETING_TYPE_BROWSER");

// Create and set list of browser assigned targeting options.
ArrayList<AssignedTargetingOption> createBrowserAssignedTargetingOptions =
   new ArrayList<AssignedTargetingOption>();
for (String targetingOptionId : create-browser-targeting-ids) {
 createBrowserAssignedTargetingOptions.add(new AssignedTargetingOption()
     .setBrowserDetails(
         new BrowserAssignedTargetingOptionDetails()
             .setTargetingOptionId(targetingOptionId)));
}
createBrowserTargetingRequest
   .setAssignedTargetingOptions(createBrowserAssignedTargetingOptions);

// Add browser assigned targeting options to list of create requests.
createRequests.add(createBrowserTargetingRequest);

// Set create requests in edit request.
requestContent.setCreateRequests(createRequests);

// Configure the bulk edit request.
LineItems.BulkEditLineItemAssignedTargetingOptions request =
   service.advertisers().lineItems()
       .bulkEditLineItemAssignedTargetingOptions(
           advertiser-id,
           line-item-id,
           requestContent);

// Execute bulk edit request.
BulkEditLineItemAssignedTargetingOptionsResponse response = request.execute();

// Check if the response is empty.
// If not, iterate over and display new assigned targeting options.
if (response.isEmpty()) {
 System.out.print("Bulk edit request created no new AssignedTargetingOptions");
} else {
 for (AssignedTargetingOption assignedOption
     : response.getCreatedAssignedTargetingOptions()) {
   System.out.printf("AssignedTargetingOption %s was created\n",
       assignedOption.getName());
 }
}

Python

# Build assigned targeting option objects to create.
createBrowserAssignedTargetingOptions = []
for targeting_id in create-browser-targeting-ids:
createBrowserAssignedTargetingOptions.append(
    {'browserDetails': {'targetingOptionId': targeting_id}}
)

# Create a bulk edit request.
bulk_edit_line_item_request = {
  'deleteRequests': [
      {
          'targetingType': 'TARGETING_TYPE_BROWSER',
          'assignedTargetingOptionIds':
            delete-browser-assigned-targeting-ids
      },
      {
          'targetingType': 'TARGETING_TYPE_AGE_RANGE',
          'assignedTargetingOptionIds':
            delete-age-assigned-targeting-ids
      }
  ],
  'createRequests': [
      {
          'targetingType': 'TARGETING_TYPE_BROWSER',
          'assignedTargetingOptions':
            createBrowserAssignedTargetingOptions
      }
  ]
}

# Edit the line item targeting.
response = service.advertisers().lineItems()\
.bulkEditLineItemAssignedTargetingOptions(
  advertiserId=advertiser-id,
  lineItemId=line-item-id,
  body=bulk_edit_line_item_request
).execute()

# Check if response is empty.
# If not, iterate over and display new assigned targeting options.
if not response:
print("Bulk edit request created no new AssignedTargetingOptions")
else:
for assigned_targeting_option in response["createdAssignedTargetingOptions"]:
  print("Assigned Targeting Option %s was created."
        % assigned_targeting_option["name"])