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.

Retrieving 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. Depending on the targeting type, retrieval is done in one of two ways:

  • Individual retrieval or exhaustive list: Retrieval of options for the majority of targeting types can be done using the get and list methods. Use targetingTypes.targetingOptions.get to retrieve the details of a targeting option identified by a targeting type and targeting option ID. Use targetingTypes.targetingOptions.list to list all available targeting options of a given targeting type.
  • Search: Options for a small number of targeting types, such as TARGETING_TYPE_POI and TARGETING_TYPE_BUSINESS_CHAIN, must be retrieved using the search method. Use targetingTypes.targetingOptions.search to retrieve targeting options of a given type that match given query strings.

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']

PHP

// Create the page token variable.
$nextPageToken = null;

do {
    // Build the query parameters object for the request.
    $optParams = array(
        'advertiserId' => advertiser-id,
        'pageToken' => $nextPageToken
    );

    // Call the API, getting the browser targeting options for the
    // identified advertiser.
    $response = $this
        ->service
        ->targetingTypes_targetingOptions
        ->listTargetingTypesTargetingOptions(
            'TARGETING_TYPE_BROWSER',
            $optParams
        );

    // Print the resulting targeting options.
    if (!empty($response->getTargetingOptions())) {
        foreach ($response->getTargetingOptions() as $option) {
            printf(
                'Targeting Option ID: %s, Browser Display Name: %s\n',
                $option['targetingOptionId'],
                $option['browserDetails']['displayName']
            );
        }
    } else {
        print('No targeting options returned\n');
    }

    // Update the next page token.
    $nextPageToken = $response->getNextPageToken();
} while (
    !empty($response->getTargetingOptions())
    && $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 advertisers.lineItems.targetingTypes.assignedTargetingOptions.create 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"])

PHP

// Create a assigned targeting option object.
$assignedTargetingOption =
    new Google_Service_DisplayVideo_AssignedTargetingOption();

// Create and set browser details.
$details =
    new Google_Service_DisplayVideo_BrowserAssignedTargetingOptionDetails();
$details->setTargetingOptionId(targeting-option-id);
$assignedTargetingOption->setBrowserDetails($details);

// Call the API, creating the browser assigned targeting option for the
// given line item.
$result = $this
    ->service
    ->advertisers_lineItems_targetingTypes_assignedTargetingOptions
    ->create(
        advertiser-id,
        line-item-id,
        'TARGETING_TYPE_BROWSER',
        $assignedTargetingOption
    );

printf(
    'Assigned Targeting Option %s was created.\n',
    $result['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 advertisers.lineItems.targetingTypes.assignedTargetingOptions.list 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 advertisers.lineItems.targetingTypes.assignedTargetingOptions.delete 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: bulkListLineItemAssignedTargetingOptions and bulkEditLineItemAssignedTargetingOptions.

Listing targeting in bulk

advertisers.lineItems.bulkListLineItemAssignedTargetingOptions 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 use the filter query parameter to filter the results by TargetingType 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']

PHP

// Create the page token variable.
$nextPageToken = null;

do {
    // Build the query parameters object for the request.
    $optParams = array(
        'filter' => "inheritance=\"NOT_INHERITED\" OR "
            . "inheritance=\"INHERITED_FROM_PARTNER\"",
        'pageToken' => $nextPageToken
    );

    // Call the API, getting all the assigned targeting options for the
    // identified line item.
    $response = $this
        ->service
        ->advertisers_lineItems
        ->bulkListLineItemAssignedTargetingOptions(
            advertiser-id,
            line-item-id,
            $optParams
        );

    // Print the returned assigned targeting options.
    if (!empty($response->getAssignedTargetingOptions())) {
        foreach ($response->getTargetingOptions() as $option) {
            printf('Assigned Targeting Option %s found\n', $option['name']);
        }
    } else {
        print('No targeting options returned\n');
    }

    // Update the next page token.
    $nextPageToken = $response->getNextPageToken();
} while (
    !empty($response->getAssignedTargetingOptions())
    && $nextPageToken)
);

Editing targeting in bulk

advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions 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 device type assigned targeting option IDs to delete request list.
deleteRequests.add(new DeleteAssignedTargetingOptionsRequest()
   .setTargetingType("TARGETING_TYPE_DEVICE_TYPE")
   .setAssignedTargetingOptionIds(delete-device-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_DEVICE_TYPE',
            'assignedTargetingOptionIds':
              delete-device-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"])

PHP

// Create delete request list.
$deleteRequests = array();

// Create and add browser assigned targeting option IDs to delete request list.
$deleteBrowserTargetingRequest =
    new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest();
$deleteBrowserTargetingRequest->setTargetingType(
    "TARGETING_TYPE_BROWSER"
);
$deleteBrowserTargetingRequest->setAssignedTargetingOptionIds(
    delete-browser-assigned-targeting-ids
);
$deleteRequests[] = $deleteBrowserTargetingRequest;

// Create and add device assigned targeting option IDs to delete request list.
$deleteDeviceTargetingRequest =
    new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest();
$deleteDeviceTargetingRequest->setTargetingType(
    "TARGETING_TYPE_DEVICE_TYPE"
);
$deleteDeviceTargetingRequest->setAssignedTargetingOptionIds(
    delete-device-assigned-targeting-ids
);
$deleteRequests[] = $deleteDeviceTargetingRequest;

// Create create request list.
$createRequests = array();

// Create and populate list of browser assigned targetion options to create.
$createBrowserAssignedTargetingOptions = array();
foreach (create-browser-targeting-ids as $optionId) {
    $option = new Google_Service_DisplayVideo_AssignedTargetingOption();
    $details =
        new Google_Service_DisplayVideo_BrowserAssignedTargetingOptionDetails();
    $details->setTargetingOptionId($optionId);

    $option->setBrowserDetails($details);
    $createBrowserAssignedTargetingOptions[] = $option;
}

// Create and add browser assigned targeting option create request to create
// request list.
$createBrowserTargetingRequest =
    new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest();
$createBrowserTargetingRequest->setTargetingType(
    "TARGETING_TYPE_BROWSER"
);
$createBrowserTargetingRequest->setAssignedTargetingOptions(
    $createBrowserAssignedTargetingOptions
);
$createRequests[] = $createBrowserTargetingRequest;

// Create a bulk edit request and assign create and delete request lists.
$body =
    new Google_Service_DisplayVideo_BulkEditLineItemAssignedTargetingOptionsRequest();
$body->setCreateRequests($createRequests);
$body->setDeleteRequests($deleteRequests);

// Call the API, editing the assigned targeting options for the identified
// line item.
$response = $this
    ->service
    ->advertisers_lineItems
    ->bulkEditLineItemAssignedTargetingOptions(
        advertiser-id,
        line-item-id,
        $body
    );

// Print created assigned targeting options.
if (!empty($response->getCreatedAssignedTargetingOptions())) {
    foreach ($response->getCreatedAssignedTargetingOptions() as $option) {
        printf(
            'Assigned Targeting Option %s was created.\n',
            $option['name']
        );
    }
} else {
    print('No assigned targeting options were created.\n');
}