Today we are excited to announce the next version of the DoubleClick for Publishers (DFP) API, version 201101. Highlights of this release include the ability to define custom targeting criteria, and the new Publisher Query Language service.

Custom targeting

Custom targeting allows you to define your own targeting criteria (such as age, gender, or content) that DFP wouldn't otherwise be able to determine. To use custom targeting, you create keys and values, target your line items to those key-value pairs, and then add them to your website's ad tags.

Similar to creating ad units and then targeting them with line items, using the custom targeting API is broken into two steps. First, you will create custom targeting keys and values with the CustomTargetingService, and then you will target these keys and values with the LineItemService. To target the keys and values, set the customTargeting field with a CustomCriteriaSet object. The custom criteria set object contains the targeting expression as an ORed set of ANDed custom criteria. The leaf nodes of the tree are key-value pairs of either free-form or predefined criteria.

If you had the expression (age=17 OR (gender=male AND age=42)), this would be represented as two custom criteria sets with logicalOperator.AND, [age=17] and [gender=male, age=42] ORed together. The custom criteria sets would be children of the customTargeting field.

Below is a diagram that will help you understand how the tree must be organized. The first level is the customTargeting field of the line item. The second level is the ORed custom criteria sets, the children of customTargeting. The final level is the custom criteria that belong to each custom criteria set, ANDed together.

In the above example of (age=17 OR (gender=male AND age=42)), the custom criteria set would look something like this:

For more examples on how to create and target custom criteria, please see the CreateCustomTargetingKeysAndValuesExample.java example as well as the TargetCustomCriteriaExample.java example.

Publisher Query Language service

The new PublisherQueryLanguageService allows you to query for data in the DFP network. You can use the service to pull information about geographical targeting that you could only previously retrieve by downloading one of the CSVs on the geographical targeting page. You can retrieve all targetable cities, for example, by sending a PQL statement like:

SELECT * FROM City where targetable = true

You would receive a ResultSet object similar to the one found in JDBC. Notice that we have included the targetable column in each of our tables to select on locations which can be successfully targeted in line items. A full list of tables can be found on the services reference page and we plan to expand this to other tables in the future.

New release notes page

With this new version, we have also modified our release notes page to give you a better per-object breakdown of new and deprecated fields and services. This will make upgrading your implementation that much easier.

Custom criteria targeting has been our most requested feature and we are eager to receive any feedback you may have through our forum. Also, if there are any blog posts about specific topics you may want, please do not hesitate to make requests on our forum as well.

– Adam Rogal, DFP API Team

Recently we launched v201004, and with that introduced the new Statement object which gives support for one of our top requested features - bind variables. In this blog post, we will take a closer look at the Publisher Query Language (PQL), Statements with bind variables, and what we have in store for the future.

Publisher Query Language

PQL plays a very significant role in the DFP API by providing the developer with a robust way of filtering which objects should be retrieved or modified before the request is completed. In other words, if you would like to retrieve only orders which are in the draft state, you could take one of two approaches. You could fetch all orders within your network and filter them one by one or instruct the server to only fetch orders in the draft state before returning all results. By doing the latter, the DFP API allows developers to create smaller and more direct requests, and, in turn, increases the efficiency of their code.

PQL has a very similar syntax to SQL, but does not include keywords such as SELECT or FROM; they are implied by the method which uses the PQL statement. The following piece of code constructs a Statement capable of fetching orders in the draft state and retrieves those orders:

  // Create a statement to only select orders in the
  // 'DRAFT' state. 

  Statement filterStatement = new Statement();

  filterStatement.setQuery("WHERE status = 'DRAFT' LIMIT 500");

  OrderPage orderPage =
      orderService.getOrdersByStatemet(filterStatement);

The documentation included for each "get*ByStatment" (e.g. getOrdersByStatement) method indicates which PQL fields map to which object properties.

Paging

The result for "get*ByStatment" calls are pages specific to the service; i.e. an OrderPage is returned by getOrdersByStatement. The limit for the number of objects that can be fetched for a single PQL request, and in a single Page, is 500. Because of this, you should always include LIMIT 500 in your statement. However, if you would like to fetch more than 500 objects, you will need to page through the results by including an OFFSET <#> in your statement as well. To page through orders in groups of 500, for example, in your statement, you would include LIMIT 500 as well as an OFFSET of an interval of 500.

This can be represented by the following code:

  // Sets defaults for page and filter.  

  OrderPage page = new OrderPage();

  Statement filterStatement = new Statement();

  int offset = 0;

  do {

    // Create a statement to get all orders.

    filterStatement.setQuery(
        "WHERE status = 'DRAFT' LIMIT 500 OFFSET " + offset);

    // Get orders by statement.

    page = orderService.getOrdersByStatement(filterStatement);

    if (page.getResults() != null) {

      int i = page.getStartIndex();

      for (Order order : page.getResults()) {

        System.out.println(i + ") Order with ID \""

          + order.getId() + "\", name \"" + order.getName()

          + "\", and advertiser ID \"" + order.getAdvertiserId()

          + "\" was found.");

        i++;

      }

    }

    offset += 500;

  } while (offset < page.getTotalResultSetSize());

The loop will end when there are no pages left, i.e. the offset is greater than or equal to the to the total result set size.

Bind variables

Bind variables were recently introduced to allow for reusing of the same template PQL statement combined with varying parameters. To change the PQL statement above to differ which status is being selected, 'DRAFT' is changed to the bind variable status, represented by :status. Note that bind variables can be any name - not just the name of their property. We chose :status here for simplicity.

  // Create a statement to only select orders in the state
  // bound to status.

  Statement filterStatement = new Statement();

  filterStatement.setQuery("WHERE status = :status LIMIT 500");

To bind to :status, you will need to create a parameter map with a String_ParamMapEntry coupling :status with a StringParam. Note that ":" is not included in the bind variable name in the parameter map.

  // Create the string parameter.
  StringParam stringParam = new StringParam();

  // Create bind parameters map.
  String_ParamMapEntry[] paramMap = new String_ParamMapEntry[] {
      new String_ParamMapEntry("status", stringParam)
  };

  filterStatement.setParams(paramMap);

 Before you make the call to getOrdersByStatement, set the stringParam value to the specific status.

  stringParam.setValue("DRAFT");

In this case, because status was bound to a variable declared before the parameter map, you can set the variables value at any time.

The first iteration of the while loop above would then produce the following XML snippet:

  ...
  <filterStatement>

    <query>WHERE status = :status LIMIT 500 OFFSET 0</query>

    <params>

      <key>status</key>

      <value  xmlns:ns2=
          "https://www.google.com/apis/ads/publisher/v201004"  
          xsi:type="ns2:StringParam">

        <value>DRAFT</value>

      </value>

    </params>

  </filterStatement>

  ...

Planned features and production

The release of v201004 was the culmination of the last step before we can begin rolling out access to the production API and we will have more information about signing up to for production use in the coming weeks. We are still hard at work on the forecasting and reporting service and will have some news about those in the following weeks as well.

We appreciate all of the great feedback we've been receiving on the forum, both on the API and the client libraries, and we''ll continue to incorporate it as we continue development.

-- Adam Rogal, The DoubleClick for Publishers API Team