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

Today, we are pleased to announce the launch of the latest version of the DoubleClick for Publishers (DFP) API. The latest version of the API (v201010) includes several exciting new features including geographical targeting. To learn how to use geographical targeting in the DFP API, please review the instructions below.

Geographical targeting

You can find geographical targeting as a new field of the LineItem.targeting property. Note that this field was added as part of the new version in a way that backwards compatibility is maintained. As we release new features, we will continue to do so in a backwards compatible manner.

The geographical targeting API is very similar to what you may have seen in the DFP UI, ranging form countries to cities which can be included or excluded as criteria. The rules for how these locations can be targeted are present in the description of the GeoTargeting class. Below is an example of how you would target the United States and Quebec, Canada, but exclude Chicago and the New York metro area.

// Get the LineItemService.
LineItemServiceInterface lineItemService =
    user.getService(DfpService.V201010.LINEITEM_SERVICE);

// Create geographical targeting.
GeoTargeting geoTargeting = new GeoTargeting();

// Include the US and Quebec, Canada.
CountryLocation countryLocation = new CountryLocation();
countryLocation.setCountryCode("US");
RegionLocation regionLocation = new RegionLocation();
regionLocation.setRegionCode("CA-QC");
geoTargeting.setTargetedLocations(
    new Location[] {countryLocation, regionLocation});

// Exclude Chicago and the New York metro area.
CityLocation cityLocation = new CityLocation();
cityLocation.setCityName("Chicago");
cityLocation.setCountryCode("US");
MetroLocation metroLocation = new MetroLocation();
metroLocation.setMetroCode("501");
geoTargeting.setExcludedLocations(
    new Location[] {cityLocation, metroLocation});

// Create the line item.
LineItem lineItem=new LineItem();
lineItem.setName("Geo targeted line item");
lineItem.setTargeting(
    new Targeting(geoTargeting, inventoryTargeting));

// Finish setting line item properties...

// Create the line items on the server.
lineItem = lineItemService.createLineItem(lineItem);

Note that some locations use ISO codes, while some use friendly names. These codes can be found on the geographical targeting code list page and can also be downloaded as CSVs from the links at the top of that page.

What else is new?

In addition to geographical targeting, v201010 includes several other changes and improvements. All of these changes can be found here.

As we continue to release new features to our API, we look forward to receiving your feedback on our forum.

-- Adam Rogal, DFP API Team