Today, we are announcing the deprecation of versions v201101, v201010, and v201004 of the DFP API. In 3 months, on August 22nd, these versions will be turned off. We are turning off older versions to make sure that everyone can benefit from the improvements in more recent releases and so that we can focus on releasing new features.

We will always give at least 3 months notice before turning off a version. We will also supply information on migrating from deprecated versions on our release notes page . We suggest that if you aren’t using one of our client libraries , now would be a great time to start.  In the client libraries, we provide lots of code examples that you’ll be able to use as a “rosetta stone”, going from one version to the next. Since this may be the first migration for many of you, below are some tips for migrating from v201004.

Bind variables have been renamed to Value

In v201004, bind variables were named Params . In v201101, they were renamed to  Values . To migrate your code, you may have to instantiate the new Value class instead of Param. You will also have to consider that Statement  now takes an array of String_ValueMapEntry .

Authentication changes

Tokens are now wrapped in a complex type. For example, where you would once just put <authToken>, you now include an <authentication> element with the proper xsi-type i.e. xsi-type=”ns1:ClientLogin” (where ns1 is the DFP API namespace). For a full discussion of this change, see the blog post on Announcing v201103 .

New targeting

Several targeting features  have been added since v201004. These include geographical , day-time , user domain , and custom targeting . If you were setting these targeting options for lineitems on the DFP website and not including them in the API, you may have already been messaged that you should update your API version.

Reporting changes

There were a few changes to reporting introduced in v201103. In v201004, ReportQuery  could have a custom startDateTime  and endDateTime . To align the API with the features of the product, the ReportQuery  object now only takes dates for startDate  and endDate . Furthermore, this also fixes an issue where an additional day past the endDateTime was being returned. When migrating, you may be able to remove this custom code that fixed this behavior.

We hope that these tips will help you migrate your code faster and if you have any feedback or comments about this deprecation, or the API in general, please feel free to leave them on our forum .

Adam Rogal, DFP API Team

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 announcing the next version of the DoubleClick for Publishers (DFP) API - version 201103. In this release, you’ll find added new targeting features, updated authentication methods, and increased performance of the reporting service. A full changelog for v201103 can be found on the release notes page .

New targeting features

In v201103, two new targeting features have been added: time and day targeting (day-parting) and user domain targeting . With day-part targeting, the user can set up which times of day a particular ad should run, and either in the timezone of the browser or publisher network. The snippet of code below shows you to target a line item to only serve ads on the weekends of a website user.

DayPartTargeting dayPartTargeting = new DayPartTargeting();
dayPartTargeting.setTimeZone(DeliveryTimeZone.BROWSER);

// Target only the weekend in the browser's timezone.
DayPart saturdayDayPart = new DayPart();
saturdayDayPart.setDayOfWeek(DayOfWeek.SATURDAY);
saturdayDayPart.setStartTime(
    new TimeOfDay(0, MinuteOfHour.ZERO));
saturdayDayPart.setEndTime(
    new TimeOfDay(24, MinuteOfHour.ZERO));

DayPart sundayDayPart = new DayPart();
sundayDayPart.setDayOfWeek(DayOfWeek.SUNDAY);
sundayDayPart.setStartTime(new TimeOfDay(0, MinuteOfHour.ZERO));
sundayDayPart.setEndTime(new TimeOfDay(24, MinuteOfHour.ZERO));
dayPartTargeting.setDayParts(
    new DayPart[] {saturdayDayPart, sundayDayPart});

targeting.setDayPartTargeting(dayPartTargeting);
lineItem.setTargeting(targeting);

User domain targeting allows the user to target specific domains from which to allow or disallow viewing of ads. The following snippet of code shows you how to restrict ads to not serve to users coming from IP addresses from “usa.gov” domain.

UserDomainTargeting userDomainTargeting =
    new UserDomainTargeting();
userDomainTargeting.setDomains(new String[] {"usa.gov"});
userDomainTargeting.setTargeted(false);
lineItem.setTargeting(userDomainTargeting);

Authentication changes

Along with targeting feature updates, the API has also changed the way authentication is handled. Previously, a RequestHeader object could contain both an authToken and an oAuthToken, which would cause an AMBIGUOUS_SOAP_REQUEST_HEADER exception if both were present. Now, we’ve replaced both the authToken and oAuthToken field with an authentication field, which takes a complex type of either ClientLogin or OAuth; this enables seamless integration of new authentication mechanisms.

For using the ClientLogin authentication mechanism, you would do:

<soapenv:Header>
  <ns1:RequestHeader
      xmlns:ns1=
        "https://www.google.com/apis/ads/publisher/v201103"
      soapenv:actor=
        "http://schemas.xmlsoap.org/soap/actor/next"
      soapenv:mustUnderstand="0">
    <ns1:networkCode>...</ns1:networkCode>
    <ns1:applicationName>...</ns1:applicationName>
    <ns1:authentication xsi:type="ns1:ClientLogin">
      <ns1:token>...</ns1:token>
    </ns1:authentication>
  </ns1:RequestHeader>
</soapenv:Header>

Likewise for OAuth authentication, you would do:

<soapenv:Header>
  <ns1:RequestHeader
      xmlns:ns1=
        "https://www.google.com/apis/ads/publisher/v201103"
      soapenv:actor=
        "http://schemas.xmlsoap.org/soap/actor/next"
      soapenv:mustUnderstand="0">
    <ns1:networkCode>...</ns1:networkCode>
    <ns1:applicationName>...</ns1:applicationName>
    <ns1:authentication xsi:type="ns1:OAuth">
      <parameters>
        OAuth oauth_consumer_key="...",
        oauth_nonce="...", oauth_signature="..."
      </parameters>
    </ns1:authentication>
  </ns1:RequestHeader>
</soapenv:Header>

Notice that in this case the authentication tag is xsi-typed as ns1:OAuth. Setting OAuth Authentication header will still work as it did before. For more information please see the authentication section of the developer’s guide.

Report enhancements

We’ve also improved the stability of the ReportService and changed the way reports with custom dates are fetched. Previous to v201103, ReportQuery could have a custom startDateTime and endDateTime. To align the API with the features of the product, the ReportQuery object now only takes dates for startDate and endDate. Furthermore, this also fixes an issue where an additional day past the endDateTime was being returned.

As always, we take developer feedback very seriously and we look forward to any feature requests on our forum .

-- Adam Rogal, DFP API Team

We recently an announced an advanced opt-in 2-step verification process to help make your Google Accounts significantly more secure. 2-step verification adds an extra layer of security to your Google Account by requiring unique “verification codes” in addition to your username and password at sign-in. This means that if your password is stolen, you still have an extra line of defense against a potential hijacker.

Enabling 2-step verification on a Google Account associated with an DFP Account may lead to an authentication issue when using the DFP API, which uses ClientLogin ClientLogin provides the authentication functionality used by the DFP API, and is not designed to ask for the verification codes in addition to the password. Therefore, APIs accessing this interface must instead use a special password called an application-specific password.

For 2-step verification users, the ClientLogin API will return an error indicating that the user needs to use an application-specific password if the user tries to login with his regular account password. When this happens the response will contain an extra field that indicates that the error was due to a missing 2-step verification code, and not incorrect credentials.

    Error=BadAuthentication
    Info=InvalidSecondFactor
   

We recommend that your application detect this error and remind the user to use an application-specific password. The API doesn’t accept verification codes, but application-specific passwords can be created for an account that allow authentication without a verification code. These can be used in the ClientLogin API just like regular passwords, and they do not expire. To obtain an application-specific password, the user needs to log in to their Google Account and click on "Authorizing applications & sites ."

Under the application-specific passwords section, they should provide the name of the tool or application for which they wish to generate a password. The generated password will only be displayed once, and although it can’t be recovered later it can be revoked at any time.

Here’s what the generated password looks like:

To learn more about application-specific passwords, visit the Google Accounts Help Center Official Google Blog for the complete announcement.

As always, please post any questions to the DFP API Forum .

-- Adam Rogal, DFP API Team

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

We are happy to announce the release of our new DoubleClick for Publishers .NET client library.The DoubleClick for Publishers API .NET Client Library makes it easier to write .NET clients which access the DFP platform.

Main features include:

• Support for .NET SDK 2.0 and above.

• Outgoing and incoming SOAP messages are monitored and logged.

• Support for API calls to sandbox and production environments.

• As opposed to autogenerated stubs from wsdl.exe, you don't have to specify xxxSpecified = true for each nullable property.

• Support for specific DFP exceptions instead of generic SoapExceptions.

Additional information can be found at the DFP API code site’s client libraries page.

Bugs and feature requests can be filed at https://code.google.com/p/google-api-dfp-dotnet/issues/list.

Please post any questions or feedback to the DFP API Forum.

– Adam Rogal, 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