v201104 - Simplified APIs for geographical targeting and custom criteria

The next version of the DoubleClick for Publishers (DFP) API, version 201104, is now available. In this release, we've made some updates to LineItem targeting. Specifically, you’ll find a more consistent geographical targeting interface as well as a simplified CustomCriteria API.

A full changelog for v201104 can be found in the release notes.

GeoTargeting

From this version of the API onward, when targeting a LineItem to a geographical location, ID numbers are now used to identify locations instead of string values. Specifically, when creating your Targeting, you won't use RegionLocation, MetroLocation, CityLocation, or CountryLocation objects, and thus, there's no need to pass strings such as "Chicago" or "US."

Instead, whether you’re targeting a country or a city, you simply create a Location object using only its ID number, where the ID number corresponds to a given country, city, etc.

After you pass the Location object to the service, in either a create or update method call, the Location object will return as the corresponding subclass, e.g. MetroLocation, CityLoction, or CountryLocation; this is to simplify the targeting process while still providing meaningful data about your locations.

Here’s an example of creating a Location object using only its ID number and handing it to a GeoTargeting object.

Location regionLocation = new Location();
// Target New York City.
regionLocation.setId(1023191L);
geoTargeting.setTargetedLocations(
    new Location[] {regionLocation});

To find the IDs of the locations you wish to target (New York City in our example), you'll need to call the Publisher Query Language (PQL) service, as shown below.

// Get the PublisherQueryLanguageService.
PublisherQueryLanguageServiceInterface pqlService =
    user.getService(
        DfpService
            .V201104.PUBLISHER_QUERY_LANGUAGE_SERVICE);

// Create statement to select all targetable cities.
StatementBuilder statementBuilder =
new StatementBuilder(
    "SELECT id, CityName FROM City"
    + "WHERE targetable = true AND CityName = ’New York’");

// Get all cities.
ResultSet resultSet = pqlService.select(
    statementBuilder.toStatement());

// Now grab the ID from the resultSet.
Row row = resultSet.getRows(0);
String[] values = PqlUtils.getRowStringValues(row);
String id = values[0];

Alternatively, note that you can also manually look up the ID for a given region in our documentation.

If you'd like to see a complete example, GetAllCitiesExample demonstrates how to query the PQL service for the relevant IDs, while CreateLineItemsExample demonstrates using the IDs for GeoTargeting.

CustomCriteria

The CustomCriteria interface has been simplified in a similar way. Custom targeting keys and values are now exclusively referenced by their ID numbers. Due to this change, the API no longer provides predefined or freeform CustomCriteria. Instead, keys and values must be created ahead of time, then referenced by ID in the CustomCriteria object.

First, you must create the key and value objects. See the original CustomCriteria announcement for a demonstration.

Once the key and value objects have been created, the next step is to plug in the corresponding IDs into the CustomCriteria object.

// Create custom criteria.
CustomCriteria customCriteria = new CustomCriteria();

// Grab the IDs of the keys and values you wish to target.
Long keyId = ...
Long valueId1 = ...
Long valueId2 = ...

// Assign the keys and values.
customCriteria.setKeyId(keyId);
customCriteria.setValueIds(new long[] {valueId1, valueId2});

// CustomCriteria allows us to target either as IS or IS_NOT.
customCriteria.setOperator(
    CustomCriteriaComparisonOperator.IS);

For further insight, please look at CreateCustomTargetingKeysAndValuesExample and TargetCustomCriteriaExample .

As always, we love to hear from our developers and we look forward to any and all feedback on our forum.

-- David Kay, DFP API Team