Google Ads Developer Blog

Announcing v201508 of the DFP API

2015-08-25T10:48:00.000-07:00

It’s finally here, the release ~~everyone~~ some of you have been waiting for: v201508. I know you’re excited and probably want to go download an updated version of the client library right away, but give me a second to tell you why you should be excited.

We’ve improved the reconciliation services in the DFP Sales Manager API, making for easier updates and reporting. There’s a bunch of changes to trafficking creatives giving you more control and visibility over your creative library. We’re also cleaning house on reporting, making the columns and dimension attributes you know and love that much easier to use.

(see full release notes here).

DFP Core

DFP trafficking objects received a few facelifts in this version.

We removed IDs from CreativePlaceholders (don’t worry, they weren’t being used anywhere).
On the creatives front, we switched Flash creatives over to use CreativeAssets, which should make duplicating and reusing flash creatives much easier. And we added CreativePolicyViolations to each creative so you can know exactly why a creative or line item was paused.
We’ve updated line item creative associations by adding a DeleteLineItemCreativeAssociations action to match UI functionality. It should be noted that deleting them is a permanent action and not simply a change in status. Deleted LICAs will no longer be accessible in the UI or API.

Sales Manager

If it’s been your dream to reconcile your delivery and billing data at the line item level, you should probably sit down for this, because featured in this release is the addition of the ReconciliationLineItemReportService which brings parity to the reconciliation process in the UI.

Additionally, we’re adding a few replacement DimensionAttributes to our ReportService - PROPOSAL_LINE_ITEM_LAST_RECONCILIATION_DATE_TIME, PROPOSAL_LINE_ITEM_RECONCILIATION_STATUS, and their LINE_ITEM_* equivalents to use for when you start reconciling line items. See the related blog post on the removal of the RECONCILIATION_RECONCILIATION_STATUS and RECONCILIATION_LAST_DATE_TIME columns found here.

Reporting

We’ve removed all DimensionFilters, as stated earlier this year (ones that have significant usage are replaced with PQL filters), added two new dimensions for ORDER_DELIVERY_STATUS as well as AGGREGATED_DEMAND_CHANNEL, and renamed the Nielsen metrics from NIELSEN_OCR_* to NIELSEN_*.

As a reminder, with each new release comes a new deprecation. If you're using v201408 or earlier, it's time to look into upgrading. If you have any questions about upgrading, let us know on the developer forum.

- Nicholas Chen, DFP API Team

Integrating with DFP as a third party

2015-08-19T07:42:00.002-07:00

Does your company want to provide third-party services for DFP but is unsure how to get started? If so, you're in luck! We've just published a new guide on how to integrate with DFP as a third party. The guide covers the major topics that new integrators commonly run into:

How to get started.
How to test your DFP integration.
How to properly set up authentication to access a client's network.
How to keep up to date with API versions.
Where to get support.

All this information can be yours just by visiting our guide.

If you have any questions, feel free to drop us a line on the DFP API forums or the Ads Developer Google+ page. - Vincent Tsao, DFP API Team

Sunset of the v201405 DFP API

2015-08-11T09:11:00.000-07:00

On Monday, August 31, 2015, in accordance with the deprecation schedule, v201405 of the DFP API will be sunset. At that time, any requests made to v201405 will return errors.

If you're still using v201405, now's the time to upgrade to the latest release and take advantage of fresh new features like DeliveryForecasts. To do so, check the release notes to identify any breaking changes, grab the latest version of your client library and update your code.

Some changes to look out for:

The endpoint URL for requests has changed from https://www.google.com to https://ads.google.com. We updated this in the default settings of our client libraries, but double check your local configuration files as well.
LineItem.startDateTime and LineItem.endDateTime now require a timeZoneID. You can retrieve all the supported time zone IDs from the Time_Zone PQL table.
The ForecastService was given a facelift, adding support for a new kind of forecast and more granular breakdowns.
All MERGED_* reporting metrics have been deprecated and removed.
The ReportService's getReportJob is now getReportJobStatus. The new method returns only the ReportJobStatus, not the entire ReportJob.

This is not an exhaustive list, so as always, don't hesitate to reach out to us with any questions.

- Chris Seeley, DFP API Team

Changes to DFP Reporting, now with more deprecation!

2015-08-04T11:32:00.000-07:00

After our last round of spring cleaning, we've gone back to the drawing board to take another look at how we could make reporting better. There currently is an abundance of Dimensions, DimensionAttributes, and Columns (and more coming with each release), so in an effort to simplify the list of fields, we will be sunsetting the following reconciliation-related dimension attributes / columns in all versions. This will happen on September 1, 2015.

Columns with equivalent replacements:

RECONCILIATION_LAST_DATE_TIME replaced by dimension attribute: PROPOSAL_LINE_ITEM_LAST_RECONCILIATION_DATE_TIME and LINE_ITEM_LAST_RECONCILIATION_DATE_TIME
RECONCILIATION_RECONCILIATION_STATUS replaced by dimension attribute: PROPOSAL_LINE_ITEM_RECONCILIATION_STATUS and LINE_ITEM_RECONCILIATION_STATUS

Columns without equivalent replacements:

LINE_ITEM_RECONCILED_RATE (in <= v201502)
CONTRACTED_REVENUE_CONTRACTED_PLACEMENT_NET_REVENUE (in <= v201411)
CONTRACTED_REVENUE_CONTRACTED_PLACEMENT_GROSS_REVENUE (in <= v201411)
DISCOUNT_BREAKDOWN_ADDITIONAL_ADJUSTMENT (in <= v201411)

While the first two have equivalent replacements, the latter ones are not being replaced, as they don’t exist in core product reporting either.

This means that usage of these columns / dimension attributes will begin throwing errors in all versions starting September 1st. If your network is actively using any of these, please update your reports to switch to the supported fields or remove them entirely. If you have any questions, comments, or concerns about this, you know where to reach us!

- Nicholas Chen, DFP API Team

Help me help you (improve the DFP API)

2015-07-30T18:03:00.000-07:00

Believe it or not, the DFP API Team eat, breathe, and live the DFP API. We wake up in the morning thinking, "How can I make the DFP API even better?" Seriously, I have had dreams about the API. It’s weird, but I’m not embarrassed to admit that.

In an effort to delight our developers even more, we’re turning the proverbial mic over to you - our customers - to help us help you. Here’s your chance to let us know how we could be better – better support, better features in the client libraries, better content in workshops, better examples, better haircuts... really, anything. Simply fill out our survey with your thoughts here.

- Nicholas Chen, DFP API Team

Some minor DFP API changes related to creatives

2015-06-30T09:09:00.000-07:00

Hello, DFP API developers! We just wanted to let you know of some minor DFP API changes that affect all versions of the API. Most likely these won’t affect your integration with DFP, but we’re announcing them here for transparency.

Deleted line item creative associations (LICAs) are no longer persisted

Deleted LICAs are no longer persisted in the product. This will affect all versions of the API. There are two things to be aware of as a result of this. First, the method getLineItemCreativeAssociationsByStatement will no longer include these deleted LICAs. Second, if you’re syncing your LICAs daily, you may notice fewer LICAs coming back. As a reminder, you can always use the action DeactivateLineItemCreativeAssociations if you want to keep them around, but not use them. This change is already in effect.

Creative placeholders are no longer assigned an ID

We are also getting rid of CreativePlaceholder.id because it is not used or referenced anywhere in the API. This field will be removed in v201508. For all versions prior to v201508, this ID now comes back as 0, instead of an ID assigned by Google. This change is also already in effect.

If you have any concerns or questions about these changes, you can always contact us on the DFP API forums and we’ll be glad to help you out.

- Vincent Tsao, DFP API Team

Help us help you with your DFP API questions

2015-06-11T13:42:00.000-07:00

If you’re a DFP developer using our API, no doubt you’ve had a question or two at some point during your integration with DFP. You’ve probably visited the DFP API forums, if not posted to them. Today we just wanted to remind you of a few simple things you can do to help us answer your API questions more efficiently.

Let us know who you are

Including the following information with every question you ask helps reduce the turnaround time for your question:

your network code
the user ID of the DFP user you’re authenticating as

Send us SOAP logs

SOAP logs contain the raw XML that describes the requests and responses of the API calls you make. These logs can help narrow down issues much faster. If you’re using one of our client libraries, you can visit its GitHub page to learn how to enable logging. For example, Java’s is here.

Here are some additional tips around SOAP logging.

When sending us logs, try to send the minimal amount of SOAP logs that clearly show the error or issue that’s occurring. If you send your entire SOAP log for the day, it’ll take longer for us to go through and increase your turnaround time.
If you’re seeing errors in your production environment and don’t have full SOAP logging enabled due to space constraints, consider logging only request IDs from the SOAP response instead. Not all errors will necessarily have a request ID, but if they do, that ID can help us look up your error.
If you’re not comfortable posting SOAP logs on the forums, you can either (1) paste a snippet of your code instead, or (2) reply directly to us by using reply privately to author.

Distinguish a product issue from an API specific issue

Generally, if an error or issue occurs in both the DFP web UI and API, it is most likely a product-level issue and non-specific to the API. To help determine this, you can try reproducing what you’re doing via the API in the web UI to see if you get the same error or issue. Product-level issues are better handled by your account manager or by posting to the DFP product forums.

If you’re still unsure, you can always post your issue in the API forums and we will be glad to help you out.

- Vincent Tsao, DFP API Team

Announcing v201505 of the DFP API

2015-05-19T11:16:00.000-07:00

Today we are releasing v201505 of the DFP API. This release brings changes to the ReportService and new features to the Sales Manager API, including advanced ProposalLineItem actions.

In v201505, the ReportService loses all MERGED_* metrics. These metrics, relics from DART migrations, are being deprecated. For more details, check out our earlier blog post. Additionally, the getReportJob method has been replaced by getReportJobStatus. The report utilities in our client libraries have been updated, but you should verify this in your code as well. Migration is straightforward, as shown in this Java example:


    // v201502 code
    ReportJobStatus status = reportService.getReportJob(reportJobId).getStatus();

    // v201505 code
    ReportJobStatus status = reportService.getReportJobStatus(reportJobId);

Sales Manager users get new ProposalLineItem actions, including ActualizeProposalLineItems and ReleaseProposalLineItems. You can also use BypassProposalWorkflowRules and include a comment when approving workflow requests.

For a full list of these and other changes, check the release notes.

As a reminder, with each new release comes a new deprecation. If you're using v201405 or earlier, it's time to look into upgrading. If you have any questions about upgrading, let us know on the developer forum.

- Chris Seeley, DFP API Team

Sunset of v201403 of the DFP API

2015-04-27T11:12:00.000-07:00

It's that time again - time to say goodbye to another version of the DFP API. In accordance with our deprecation schedule, v201403 has been deprecated and is scheduled for sunset on Tuesday, June 30 2015. At that time, any requests made to v201403 will return errors.

If you're currently using v201403, there's still time to migrate to the latest and greatest v201502. To do so, check the release notes to identify any breaking changes, grab the latest version of your client library, and update your code!

Things to look out for include:

OAuth SOAP headers are no longer supported. You'll need to pass authentication information in HTTP headers instead. If you're using a client library, we took care of this for you.
Line item fields unitsBought and unitType have moved into the Goal object.
The endpoint URL for requests has changed from https://www.google.com to https://ads.google.com. We updated this in the default settings of our client libraries, but double check your local configuration files as well.
LineItem.startDateTime and LineItem.endDateTime now require a timeZoneID. You can retrieve all the supported time zone IDs from the Time_Zone PQL table.
The ForecastService got a facelift, including renaming existing methods and adding support for a new kind of forecast.

This is not an exhaustive list, so as always don't hesitate to reach out to us on our API forum with any questions.

- Chris Seeley, DFP API Team

Important upcoming breaking changes to DFP reporting

2015-04-23T12:26:00.000-07:00

Now that it’s spring again (in the Northern Hemisphere at least), it’s time for DFP’s annual spring cleaning! In this edition, we’ll be doing some pruning of our ReportService. What does this mean for you? We’re sunsetting some reporting dimensions, attributes, and metrics in existing versions (before the version is fully sunset), so your reports will break if you don’t migrate before the shutoff dates. I know what you’re wondering: “should I panic?”. Absolutely not. This type of behavior rarely occurs, so as long as you phase out usage for these particular fields, you should be fine moving forward.

Merged Metrics

Remember when Doubleclick for Publishers was called DART? I, too, get nostalgic about our old ad server, but it’s been a couple of years since we transitioned to the new DFP platform, and it’s just about time when the merged reporting columns are no longer useful (these columns only existed so you could continue reporting on delivery that spanned DART and DFP). In all versions after v201502, we will no longer provide merged reporting columns and dimension attributes in the API, that is, anything starting with 'MERGED_' or contains '_LIFETIME_MERGED_.' After August 1, 2015, these columns and dimension attributes will stop returning data entirely and will return INVALID_COLUMNS in all versions that still include them.

There are three scenarios in which you’re using these columns:

Just for fun.
Because you forgot you’re using them.
Because you have lifetime line items that have carried over from DART (in which case you’ll have to recreate these). To give you an example, if the metric you care about is impressions, you can get the DART delivery portion by subtracting the portion of delivery from DFP Premium (AD_SERVER_IMPRESSIONS) from the MERGED value (MERGED_AD_SERVER_IMPRESSIONS) which represents the aggregate DART and DFP Premium volume. Additionally, you should make the switch to the non-merged columns and dimension attributes as soon as possible.

Dimension Filters

But wait, there’s more! Our next API version (v201505) will be the last to support some of our infrequently used dimensionFilters.

MOBILE_LINE_ITEMS
WEB_INVENTORY_UNITS
MOBILE_INVENTORY_UNITS
WHOLE_NETWORK
PARTNER_STATS_TYPE_ESTIMATED
ACTIVE_ADVERTISERS
PARTNER_STATS_TYPE_RECONCILED
WEB_LINE_ITEMS
ALL_SALESPEOPLE

In each of the cases above, the filters either no longer provide meaningful information (as is the case with mobile vs. web line items and ad units with platform unification complete), or weren’t being used at all.

Similar to the changes above, after August 1, 2015, these dimension filters will return an INVALID_DIMENSION_FILTERS error in any version that still includes them.

So if you’re using any of the reporting features above, consider this an early heads up (and an opportunity) to refactor some of your code for spring cleaning.

As usual, if you have any questions, comments, or concerns, don’t hesitate to let us know on the forums.

- Nicholas Chen, DFP API Team

Ads API Workshops on Display Content Now Available

2015-04-13T11:13:00.000-07:00

A few weeks back we hosted a workshop for the Display Ads APIs and SDKs where we gave presentations on the DFP API, IMA SDK, and Mobile Ads SDK. If you weren’t able to attend, or want a refresher on something you saw that day, you can check out our presentation videos and slides. If you have any questions about those videos, feel free to ask on our respective forums:

- Shawn Busolits, IMA SDK Team

LineItemService, or Line_Item PQL Table?

2015-03-30T11:13:00.000-07:00

One of the most used services in the DFP API is the LineItemService. Many of you are already utilizing the Line_Item table in the PublisherQueryLanguageService to create match tables on fields like Status or ExternalId, but with newer API versions, more and more fields are available as columns. Did you know that as of v201411 the Line_Item table includes a column for Targeting? With so many line item fields now accessible through PQL, the Line_Item table might be a viable replacement for your read operations.

What's the advantage? Faster response times. As an example, I pulled 5,000 line items from a network using both the LineItemService and the Line_Item PQL Table, printing page offsets as the results arrived. Take a look at the results:

* Actual response times may vary. Line item fields only available in participating PQL Tables.

Using the PublisherQueryLanguageService shaved off 17 seconds for a respectable speed increase of 15%.

However, if your application doesn't need some of the heavier fields, you'll see a much bigger gain. Check out what happens when we leave out Targeting:

The sparse selection offered by the PublisherQueryLangugeService means our data size is smaller, cutting the total time by a whopping 45%!

If you're looking for a performance boost in your LineItem read operations, give the Line_Item table a try. We've got example code in each of our client libraries to get you started. If you have any questions, don't hesitate to reach out to us on our API forums.

- Chris Seeley, DFP API Team

Announcing the release of DFP API v201502

2015-02-19T12:34:00.000-08:00

Today we are releasing v201502 of the DFP API. This release includes a revamp of the ForecastService, including support for Delivery forecasts. There are also new video features including GRP settings on line items, GRP breakdowns in forecasts, and new VIDEO_VIEWERSHIP report columns.

Sales Manager gains three new services for Packages, ProductPackages, and ProductPackageItems. Additionally, the ProposalLineItemService will now return ProposalLineItems that were created from Packages. There's also improved support for workflow rules with WorkflowValidationErrors.

Finally, Type fields have been removed from all entities. Please update your code to use xsi:type, class names, or instance of.

A detailed list of these and other changes can be found on our release notes page.

Using the new ForecastService

The ForecastService can now run Delivery forecasts for multiple line items. These forecasts report the number of units that will be delivered to each line item given the goals and contentions from other line items in the request. Pass prospective line items or line item IDs to getDeliveryForecast or getDeliveryForecastByIds as outlined in this Java example:

    DeliveryForecast existingLineItemForecast =
       forecastService.runDeliveryForecastByIds(new long[] {123L, 456L});

    ProspectiveLineItem prospectiveLineItem1 = new ProspectiveLineItem();
    prospectiveLineItem.setLineItem(myFirstLineItem);

    ProspectiveLineItem prospectiveLineItem2 = new ProspectiveLineItem();
    prospectiveLineItem.setLineItem(mySecondLineItem);

    DeliveryForecast prospectiveLineItemForecast = 
        forecastforecastService.runDeliveryForecast(new ProspectiveLineItem[] {
        prospectiveLineItem1, prospectiveLineItem2});

The existing getForecast and getForecastById methods have been replaced by getAvailabilityForecast and getAvailabilityForecastById, respectively. You must now include AvalilabilityTargetingOptions to specify whether you want to include contending line items or the new TargetingBreakdown.

    ProspectiveLineItem prospectiveLineItem = new ProspectiveLineItem();
    prospectiveLineItem.setLineItem(myLineItem);
    AvailabilityForecastOptions options = new AvailabilityForecastOptions();
    options.setIncludeContendingLineItems(true);
    options.setIncludeTargetingCriteriaBreakdown(true);
   
    AvailabilityForecast forecast = 
        forecastService.getAvailabilityForecast(prospectiveLineItem, options);

Handling Sales Manager Workflows with the API

Updating a Proposal with workflow rules may cause a WorkflowValidationError. The WorkflowValidationError will include a message defined by the network's administrator. For more information about detecting and handling specific error types, refer to this blog post.

As always, if you have any questions or feedback, reach out to us on our API forums.

- Chris Seeley, DFP API Team

Deprecation of active view NOT_* report columns in the DFP API

2014-12-19T08:17:00.000-08:00

In the coming weeks, we will be deprecating all ACTIVE_VIEW_NOT* report columns in v201405, v201403, v201311 and v201306 of the DFP API. These columns are no longer supported in the DFP query tool, and the DFP API is following suit. The following columns will be affected:

Column.TOTAL_ACTIVE_VIEW_NOT_VIEWABLE_IMPRESSIONS
Column.TOTAL_ACTIVE_VIEW_NOT_MEASURABLE_IMPRESSIONS

Column.AD_SERVER_ACTIVE_VIEW_NOT_VIEWABLE_IMPRESSIONS
Column.AD_SERVER_ACTIVE_VIEW_NOT_MEASURABLE_IMPRESSIONS

Column.ADSENSE_ACTIVE_VIEW_NOT_VIEWABLE_IMPRESSIONS
Column.ADSENSE_ACTIVE_VIEW_NOT_MEASURABLE_IMPRESSIONS

Column.AD_EXCHANGE_ACTIVE_VIEW_NOT_VIEWABLE_IMPRESSIONS
Column.AD_EXCHANGE_ACTIVE_VIEW_NOT_MEASURABLE_IMPRESSIONS

Column.ACTIVE_VIEW_NOT_VIEWABLE_IMPRESSIONS
Column.ACTIVE_VIEW_NOT_MEASURABLE_IMPRESSIONS

Migration
Normally all features are supported until the API version is sunset. This deprecation is a rare case where these report metrics are being disabled for existing versions due to product changes related to viewability. If you are using v201408 or later, you will not be affected by this deprecation. If you are currently using these columns in v201405 or earlier, you can replace them with their logical opposites. Alternatively, to retain the same metrics, you can calculate them from the logical opposite and the rate. For example, Column.TOTAL_ACTIVE_VIEW_NOT_VIEWABLE_IMPRESSIONS is equivalent to

Deprecation errors
If you do not migrate, your reports will return the following error:

ReportError.COLUMNS_NOT_SUPPORTED_FOR_REQUESTED_DIMENSIONS

If you have any questions or migration troubles, please reach out to us on our developer forum.

- Chris Seeley, DFP API Team

Filtering report data by custom targeting key ID in the DFP API

2014-12-05T09:06:00.001-08:00

A lot of our DFP API developers have been asking recently about how to filter report data by custom targeting key ID. Currently the DFP API allows you to filter report data by custom targeting value ID only. Until we have official support for filtering by custom targeting key ID in reports, you can use the CustomTargetingService and the ReportService together to achieve this goal.

Step 1: Use CustomTargetingService to get your keys and values

You will first need to use getCustomTargetingValuesByStatement and filter by the custom targeting keys you’re interested in to obtain all the corresponding values. For example:

    WHERE customTargetingKeyId IN (17, 18, 19)

If you have a lot of keys and values in your network, a better approach is to store these in a local database and do nightly syncs. Use getCustomTargetingKeysByStatement to obtain all the keys in your network, and then iterate through them, calling getCustomTargetingValuesByStatement for each key to obtain their values. Our client libraries all have examples of this. For instance, the Java example can be found in our ads Java client library GitHub repository. This way, you can look up the values associated with a custom targeting key more quickly and not do an additional API call.

Step 2: Use the values in a report query

Once you have the values for the custom targeting key you’re interested in, you can then use the ReportQuery.statement with the PQL IN clause to filter on the CUSTOM_TARGETING_VALUE_ID dimension. For example, say you were interested in filtering on custom targeting key ID of 7777. You look up the values of 7777 in Step 1, which gives you three value IDs: 3211, 88990, 123456. You can then use the IDs to effectively filter your report data by custom targeting key ID 7777.

    WHERE CUSTOM_TARGETING_VALUE_ID IN (3211, 88990, 123456)

However, please be aware that if you have a lot of custom targeting value IDs to filter on, you should batch them by querying for no more than 500 IDs at a time in the PQL IN clause. For example, you will run your report filtering on the first 500 IDs you’ve collected and save that report. Then you will run the same report on the next page of 500 IDs you’ve collected and so on until you have no more IDs. You can then combine the reports locally so that you have all the data for those custom targeting IDs.

If you have any questions about this, feel free to drop us a line on the DFP API forums or Ads Developer Google+ page.

- Vincent Tsao, DFP API Team

Announcing the release of DFP API v201411

2014-11-11T09:15:00.000-08:00

Today we are releasing v201411 of the DFP API. This release supports creating and updating VideoRedirectCreatives, enhances cross-sell via the new SharedAdUnitService, and adds an experimental Targeting field to the Line_Item PQL table. There are also new Sales Manager enhancements, including derived custom criteria on proposal line items and PQL filtering for Product.lastModifiedDateTime. A detailed list of these and other changes can be found on our release notes page.

Creating VideoRedirectCreatives

You can now use the DFP API to create and update externally hosted and YouTube hosted VideoRedirectCreatives. Simply set the VideoRedirectAsset.redirectUrl to the YouTube or third party URL hosting your ad:

    videoRedirectAsset.setRedirectUrl("http://0.thirdpartyadserver.com/ad.mp4")

You will also need to set the VideoMetadata information for both externally hosted and YouTube hosted ads. For streaming videos, set the minimumBitRate and maximumBitRate; for progressive videos, use the static bitRate.

Custom targeting filter changes

In DFP API v201411 CustomTargetingService.getCustomTargetingKeysByStatement and CustomTargetingService.getCustomTargetingValuesByStatement will return INACTIVE keys and INACTIVE values, respectively. You can filter them by supplying a where clause in a PQL statement:

    WHERE status = 'ACTIVE'

LineItem status changes

To better match the UI, ComputedStatus.NEEDS_CREATIVES has been renamed to ComputedStatus.INACTIVE. Use LineItem.isMissingCreatives to determine if the line item needs creatives.

Cross selling features

If your network is connected to a cross selling host, you can manage your shared ad units with the SharedAdUnitService. To determine if an AdUnit is shared, use the new isSharedByDistributor and crossSellingDistributor fields. We've also added a skipCrossSellingRuleWarningChecks field to the LineItem object so you can override any cross selling warnings.

Experimental targeting PQL column

We've heard your feedback and are adding an experimental PQL column for line item targeting. Fair warning: experimental means we may make breaking changes as we get your feedback and make improvements. The targeting column will be returned with a Value.Type of "TargetingValue", and the value itself containing a Targeting object:

    <Value.Type>TargetingValue</Value.Type>
    <value>
        <inventoryTargeting>
            <targetedAdUnits>
                 <adUnitId>33985943</adUnitId>
                 <includeDescendants>true</includeDescendants>
            </targetedAdUnits>
        </inventoryTargeting>
    </value>

If you've been waiting for a faster way to retrieve line item targeting, try it out and let us know what you think. Head over to the API forum and tell us what works for you, and how we can improve.

- Chris Seeley, DFP API Team

Minimum Java version requirement changes to client library for AdWords, AdX, DFP and DFA

2014-11-03T10:55:00.001-08:00

Are you using the Google Ads API Java Client Library and Java 5 (1.5)? If so, we have important news: starting April 2015, all releases of the Google Ads API Java Client Library will only be compatible with Java 1.6 and higher.

Why this change is happening
The primary reasons for this change are:

Starting with version 18.0, Guava will no longer release 1.5 backports. The Google Ads API Java Client Library uses Guava's precondition checks, I/O helpers, and other utilities extensively.
Java 5 is a bit outdated -- it was first introduced in May 2004, and Oracle's support for Java 5 is approaching some key end dates.
Usage of Java 5 among Google Ads API Java Client Library developers is rapidly declining.

Next steps
If you are using Java 6 or higher, then you're all set -- all releases of the client library on github already support your runtime.

If you are still using Java 5 and need to migrate to Java 6 or higher, check out the following adoption guides from Oracle:

Still have questions? Feel free to file an issue on the library's issues page or contact us via our Google+ page.

- Josh Radcliff, AdWords API Team

AdsPyGoogle Sunset on January, 5 2015

2014-11-03T10:41:00.000-08:00

As an avid reader of this blog, you have undoubtedly already seen the announcement that our dear old friend, the client library known as ‘AdsPyGoogle,’ will be sunset on January 5, 2015. Yes—we too at Google are very sad about this.

Fret not! In its place, we have a more than capable replacement in the form of our new GoogleAds Python client library which is more lightweight, has far fewer dependencies, boasts improved utilities and functionality, and perhaps most importantly, supports Python 2.7 as well as 3.x.

If you need a starting point on how to perform this switch, we have a blog post detailing the differences between the two, as well as a nifty migration guide on Github.

As usual, if you have any questions, feedback, or comments, please don’t hesitate to reach out on the DFP or AdWords forums.

- Nicholas Chen, DFP API Team

Life of a DFP Video Line Item Part I

2014-10-22T16:56:00.000-07:00

Your DFP network is already serving thousands of image, text, and custom ads. But now you want to start monetizing your video content. This two-part blog post will get you started with video ads. We'll start with creating and trafficking your ad using the DFP API, and then show you how to display it using the IMA SDK.

Before you start

If you're new to video ads, check out this help center article for a little more background. This post shows how to use a VAST redirect creative, so you'll need to host a VAST tag and your video ad before making the creative in DFP. If you just want an example VAST tag to get up and running, you can use the XML here.

Note that this example tag will only return VAST for the first request. Subsequent requests will need to update the correlator timestamp in the URL. The IMA SDK will handle this for you, so there's no problem using this as your example URL.

Creating the video ad unit

If your network doesn't have a video ad unit already, you'll need to create one. Set the fields as you would for any other ad unit, but use a size appropriate for video and the VIDEO_PLAYER environment type.

    Size videoSize = new Size();
    videoSize.setWidth(640);
    videoSize.setHeight(480);
    videoSize.setIsAspectRatio(false);

    AdUnitSize videoAdUnitSize = new AdUnitSize();
    videoAdUnitSize.setSize(videoSize);
    videoAdUnitSize.setEnvironmentType(EnvironmentType.VIDEO_PLAYER);

Making a video creative

Beginning in v201403, you can create and update VAST redirect creatives with the DFP API. If video features are enabled on your network, creating VAST redirect creatives takes just a few lines of code. Let's start by setting some standard creative fields:

    VastRedirectCreative vastRedirectCreative = new VastRedirectCreative();
    vastRedirectCreative.setName("My first VAST redirect creative");
    vastRedirectCreative.setAdvertiserId(advertiserId);

Now set the size of your video to match your AdUnit:

    Size size = new Size();
    size.setWidth(640);
    size.setHeight(480);
    vastRedirectCreative.setSize(size);

Finally, you need to set your VAST XML. For this example, we'll use VAST XML with a linear advertisement. Linear video ads are analogous to television commercials and can play before, after, or in the middle of your content.

    vastRedirectCreative.setVastXmlUrl(vastXmlUrl);
    vastRedirectCreative.vastRedirectType(VastRedirectType.LINEAR);
    Creative[] creatives =  creativeService.createCreatives(new Creative[] { 
        vastRedirectCreative});
    Creative masterCreative = creatives[0];

This is your master creative. When working with video, DFP uses CreativeSets which have master and companion creatives. Companion creatives are typically displayed alongside the content video, and tie in with the video ad. The line items you create for video will be associated with a creative set, so you need to create one using your VAST redirect creative as the master. For simplicity, we won't use any companions here.

    CreativeSet creativeSet = new CreativeSet();
    creativeSet.setName("My VAST Redirect Creative Set");
    creativeSet.setMasterCreativeId(masterCreative.getId());
    creativeSet.setCompanionCreativeIds(new long[] {});
    CreativeSet createdCreativeSet =
        creativeSetService.createCreativeSet(creativeSet);

Creating a video line item

Now we need a line item to serve the video creative set. We'll just highlight the differences for video line items here, so if you aren't familiar with creating line items, check out our complete example on GitHub.

In addition to the usual line item fields, you have the option to set position targeting. Using VideoPositionType.PREROLL will target videos where ads can play before the content starts.

    VideoPosition videoPosition = new VideoPosition();
    videoPosition.setPositionType(VideoPositionType.PREROLL);
    VideoPositionTarget videoPositionTarget = new VideoPositionTarget();
    videoPositionTarget.setVideoPosition(videoPosition);
    VideoPositionTargeting videoPositionTargeting = new VideoPositionTargeting();
    videoPositionTargeting.setTargetedPositions(
        new VideoPositionTarget[] {videoPositionTarget});

Video line items can also target content in a variety of ways with ContentTargeting. If your network is connected to a content source you can use your content hierarchies to target a genre, season, or any other hierarchy you configured. If you're unsure of how to get the content metadata hierarchy key IDs, take a look at this example.

    // Create content targeting.
    ContentMetadataKeyHierarchyTargeting contentMetadataTargeting = 
        new ContentMetadataKeyHierarchyTargeting();
    contentMetadataTargeting.setCustomTargetingValueIds(
        new long[] {contentCustomTargetingValueId});
    
    ContentTargeting contentTargeting = new ContentTargeting();
    contentTargeting.setTargetedContentMetadata(
        new ContentMetadataKeyHierarchyTargeting[] {contentMetadataTargeting});

Now add these to the line item's targeting object. Don't forget to set the environment type to VIDEO_PLAYER.

    Targeting targeting = new Targeting();
    targeting.setContentTargeting(contentTargeting);
    targeting.setVideoPositionTargeting(videoPositionTargeting);
    // Target your video AdUnit
    targeting.setInventoryTargeting(inventoryTargeting);
    
    LineItem lineItem = new LineItem();
    lineItem.setEnvironmentType(EnvironmentType.VIDEO_PLAYER);
    lineItem.setTargeting(targeting);

Make sure to set all the required fields as you would for any other line item, and then create it.

Wrapping things up

Let’s do a quick recap. We now have an AdUnit for a standard video size, our VastRedirectCreative of a matching size in a CreativeSet, and our video LineItem targeted the AdUnit. If your network has a content source connected, you may have targeted certain content as well.

The last step is to create a LineItemCreativeAssociation to connect the CreativeSet with the LineItem.

    LineItemCreativeAssociation lica = new LineItemCreativeAssociation();
    lica.setLineItemId(lineItemId);
    lica.setCreativeSetId(creativeSetId);
    LineItemCreativeAssociation[] licas =
        licaService.createLineItemCreativeAssociations(
            new LineItemCreativeAssociation[] {lica});

Finally, your video ad is ready to serve. The next question is, how do you actually serve it? Stay tuned for the exciting conclusion: Life of a Video Line Item Part II.

- Chris Seeley, DFP API Team

Sunset of DFP API v201311 and earlier, and the removal of ClientLogin

2014-10-17T11:04:00.000-07:00

This is a friendly reminder that, on February 27, 2015, we will sunset DFP API versions v201311, v201308, and v201306. At that point, requests to these versions will fail. We'll also remove them from our online documentation and the client libraries. If you are currently using one of these versions, this is an excellent time to begin migrating to a supported version. See the release notes for a list of the many new features in our recent API versions.

Going forward, all DFP API versions will follow a consistent deprecation schedule: versions will be supported for one year, deprecated for one quarter, then sunset. This means each of our quarterly API versions will be available for 15 months from the time of release. This deprecation schedule enables us to spend more time improving the latest versions with new features.

Note that v201311 is the last version that supports ClientLogin, which was officially deprecated across all of Google on April 20, 2012. If your application is not yet using OAuth2, you must migrate before Feb 27, 2015.

If this task seems daunting, don't fret, we have you covered. On our Developer page, we have a helpful OAuth2 guide to make sure the transition is as smooth as possible. As an added reason to switch, the DFP API now supports OAuth2 service accounts. You can add service account users directly in the DFP UI. For more information, see here for a guide on how to use a service account user with the DFP API.

If you have any feedback or comments about this deprecation, or the API in general, please feel free to leave them on our forum.

- Nicholas Chen, DFP API Team

Using LINQ with the DFP API

2014-09-22T10:36:00.001-07:00

By now you're probably familiar with using PQL in the DFP API. The SQL-like filtering provides an expressive way of working with DFP, but occasionally you'll want to filter on a field that isn't supported by PQL. Luckily, if you're using the .NET library, you can utilize LINQ to augment your filtering capabilities.

Filter on any field

Similar to PQL, LINQ provides a friendly syntax for filtering iterables. As you page through entities from DFP, you can leverage LINQ to add that extra filtering with just a few lines of code.

This example finds all ImageCreatives that are missing altText - a field specific to the subclass and not filterable with PQL.

    CreativePage page = new CreativePage();
    var creativesMissingAltText = new List();

    // Create statement to select image creatives.
    StatementBuilder statementBuilder = new StatementBuilder()
        .Where("creativeType = :creativeType")
        .OrderBy("id ASC")
        .Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
        .WithBindVartiableValue("creativeType", "ImageCreative");

    // Page through all creatives and select those that are missing the
    // altText property with LINQ.
    do {
      page =
          creativeService.getCreativesByStatement(statementBuilder.ToStatement());

      creativesMissingAltText.AddRange(
          from ImageCreative creative in page.results
          where creative.altText == ""
          select creative);

      statementBuilder.IncreaseOffsetBy(StatementBuilder.SUGGESTED_PAGE_LIMIT);
    } while (statementBuilder.GetOffset() < page.totalResultSetSize);

    Console.WriteLine("Found {0} ImageCreatives missing altText",
        creativesMissingAltText.Count);

While LINQ offers a way to extend filtering, it's important not to ignore PQL. You'll notice this example used PQL to pre-filter on the creative type. Working with smaller result sets will save you network overhead and processing cycles.

Filtering with regular expressions

Now let's take a look at a more complex example. In this scenario, your application needs to validate the htmlSnippet of CustomCreatives. LINQ allows you to use regular expressions while filtering to extract the matches. Here we'll use a regular expression to make sure URLs in the htmlSnippet point to a certain subdomain.

    // Make sure any URLs to mydomain go through the CDN.
    Regex subdomainRegex = new Regex(@"https?://(?!cdn\.).*?mydomain.com");
    var errors =
        from CustomCreative creative in creativesToValidate
        let matches = subdomainRegex.Matches(creative.htmlSnippet)
        where matches.Count > 0
        select new {
          creativeId = creative.id,
          matchedUrls = from Match match in matches select match.Value
        };

    foreach (var error in errors) {
      Console.WriteLine("Invalid urls found in creative {0}: {1}",
          error.creativeId, error.matchedUrls.Join(","));
    }

LINQ also supports common functions like Average and Max, making it easy to interact with DFP entities. For more LINQ examples, check out 101 LINQ Samples. You just might find the missing link you need for your DFP application.

- Chris Seeley, DFP API Team

'Decorating' your Python DFP API applications

2014-09-18T07:55:00.001-07:00

Python has tons of cool idioms and features that are often overlooked or underutilized. List comprehensions to cut back on the use of unnecessary loops, decorators to wrap functions with annotations, and generator functions are just some that can be applied to working with the DFP API.

In this post, we'll tackle one of our most asked questions using decorators: "Why am I running into CONCURRENT_MODIFICATION or QUOTA_EXCEEDED errors, and how do I avoid this?".

Addressing these errors using decorators

CONCURRENT_MODIFICATION and QUOTA_EXCEEDED errors are similar in nature - the requests you’re making are failing, but not necessarily because the data you’re sending over is bad. In the first case, one of the objects you’re trying to modify is being updated elsewhere, but you likely want to try again after pulling down the same set of objects. You could certainly write code that retries your operations in all of your services for each object, but it may get a bit hard to maintain (especially with duplicated code). A much cleaner implementation would be to use a decorator!

The Python wiki has an entry under the decorators section that shows how a generic decorator might work for retrying a call. With a few modifications, we can tailor this to capture the two types of errors that might arise:

  import time
  from functools import wraps

  RESPONSES_TO_RETRY = ['CONCURRENT_MODIFICATION', 'QUOTA_EXCEEDED']

  def retry(tries=4, delay=3, backoff=2):
      ''' Decorator that implements an exponential backoff for retrying on errors.

      Args:
        tries: int number of times to execute the wrapped function before failing
        delay: int time to delay in seconds before the FIRST retry
        backoff: int multiplier to extend the initial delay by for each retry
      '''
      def decorated_function_with_retry(func):
          @wraps(func)
          def function_to_retry(*args, **kwargs):
              local_tries, local_delay = tries, delay
              while local_tries > 1:
                  try:
                      return func(*args, **kwargs)
                  except Exception, e:
                      if [response for response in RESPONSES_TO_RETRY
                          if response in e.fault['faultstring']]:
                        print '%s, Retrying in %d seconds...' % (str(e),
                                                                 local_delay)
                        time.sleep(local_delay)
                        local_tries -= 1
                        local_delay *= backoff
              return func(*args, **kwargs)
          return function_to_retry
      return decorated_function_with_retry

Say you were making a call to update line items - with large networks, it’s not unlikely that someone might be editing the line item at the same time. Since you’d want to pull down the most recent copy of the line item any time the update fails, you would want to abstract out the update method to include the getLineItemsByStatement call, e.g.,

  @retry()
  def fetch_and_update_line_item(statement):
    # call to get the line item in question
    response = line_item_service.getLineItemsByStatement(
        statement.ToStatement())

    updated_line_items = []
    if 'results' in response:
      for line_item in response['results']:
        # Do something with your line items here and add them to
        # updated_line_items.

    line_item_service.updateLineItems(updated_line_items)

This would effectively allow you to, in the event of the update failing due to concurrent modification, pull down and update a new copy of the line item. Using the default constructor will retry 4 times with 3, 6, and 12 second delays in between.

To wrap things up, decorators are incredibly useful constructs in Python and are useful for the DFP API for several reasons:

Your application will be less flaky and less affected by intermittent application issues.
You’re less likely to run into quota errors.
This would prevent overwriting other changes (in the case of retrying failed calls on concurrent modification errors).
You could also use something like this to log errors on your end, which could help reveal poor code health or inefficient processes.

Make use of decorators in your code, and you'll soon be sitting pretty.

- Nicholas Chen, DFP API Team

Announcing OAuth 2.0 service account support for the DFP API

2014-09-15T09:34:00.000-07:00

Until now, the DFP API only supported the OAuth 2.0 native/installed application flow. The OAuth 2.0 service account flow was only supported it you had a Google Apps for Business Account. Today, we’re unveiling the new OAuth 2.0 service account flow for DFP. This authorization flow has been simplified to no longer require a Google Apps domain. We’ve also updated the DFP web UI to allow service accounts to be added to be a DFP network.

Why should I use service accounts?

Service accounts allow access to Google APIs without the need for user interaction by authenticating solely with server-to-server interactions. Other OAuth 2.0 flows require user interaction or having an application cache a refresh token.

How do I use service accounts?

Generate a service account key from the Google Developers Console.
Add the service account to your DFP network by going to the Admin tab and clicking the Add a service account user button.

Fill in the form with your Name, Email, Teams (if applicable), and Role. Then, click Save.

View existing service account users by going to the Users tab and then clicking the Service Account filter.

With the *.p12 key generated from the Google Developers Console and the service account added to the DFP network, you can now generate an OAuth 2.0 token. For example, using the Java client library:

    GoogleCredential credential = new GoogleCredential.Builder()
        .setTransport(new NetHttpTransport())
        .setJsonFactory(new GsonFactory())
        .setServiceAccountId("****@developer.gserviceaccount.com")
        .setServiceAccountScopes("https://www.googleapis.com/auth/dfp")
        .setServiceAccountPrivateKeyFromP12File(new File("/path/to/key.p12"))
        .build();

For more information, see our updated guide on using service accounts with DFP.

- Vincent Tsao, DFP API Team

Announcing v201408 of the DFP API

2014-08-20T11:58:00.001-07:00

Today, we launch v201408 of the DFP API. This release features the addition of a new table to the Publisher Query Language service, some changes to the LineItem.Goal object, a multitude of enhancements to our Sales Manager services, as well as changes to our server endpoint and scope URLs. A detailed list of these features and what’s changed can be found on our release notes page.

New Endpoint URL

Version v201408 of the DFP API changes the endpoint URL for requests from https://www.google.com to https://ads.google.com. For example:

https://ads.google.com/apis/ads/publisher/v201408/CompanyService?wsdl

All of our DFP API client libraries have been updated to reference this URL starting with the v201408 release. If you are using a supported version of the client libraries, then no changes will be required. Otherwise, please update your code to make requests against this new URL.

Line Item goals, Sales Manager refactorings, and more PQL support

In v201408, we have added the field of Goal.goalType to the LineItem.Goal; this replaces what was formerly lineItem.duration and adds back support to create / update the line item types impacted in v201405 (listed here).

We've also done some significant refactoring of our Sales Manager API services adding premiums to rateCard objects. Prior to this version, there was a RateCardCustomizationService as well as a RateCardCustomizationGroupService; both were required to add a feature premium to an existing rateCard. This has now been replaced with a singular service named PremiumRateService.

In addition, we've also heard you loud and clear that PQL tables make development easier - in v201408, we provide support for the Audience_Segment_Category table.

New OAuth 2.0 Scope

With the release of v201408 of the DFP API, we will be introducing a new OAuth 2.0 scope. This scope identifies the service that your application will access during the authorization process.

https://www.googleapis.com/auth/dfp

This new scope better aligns with the naming conventions of many of the other Google APIs.

Starting from today, you should use the new scope when authorizing access for the DFP API regardless of the DFP API version. All our current DFP API client libraries use this new scope.

But I have refresh tokens from the deprecated scope...

Don't worry if your client code is using refresh tokens authorized with the deprecated scope - they will still work. However, new authorizations should specify the new scope.

- Nicholas Chen, DFP API Team

Legacy Ads Python Client Library to sunset on January 5th, 2015

2014-08-12T07:03:00.000-07:00

As you may know, we announced the release of our new Python client library—googleads—in March, 2014. Since then, we’ve received a lot of feedback that has helped us further improve the library. Given the positive reception we’ve had with googleads, along with the improvements we’ve made to it over the past few months, the time is right for us to give our legacy Python client library—adspygoogle—a proper send-off. The legacy ads APIs Python client library has been deprecated and will be sunset on January 5th, 2015.

Between now and the sunset date, all upcoming API releases will be supported. The legacy client library will no longer be available on GitHub or PyPI after the sunset date. You can continue to use it while supported versions of the APIs are available, but it will eventually become obsolete and won’t be supported if any new issues are discovered. In order to smoothly transition to the new client library and have uninterrupted access to the newest versions of the APIs, we suggest you migrate to googleads as soon as possible. To help you migrate, we’ve prepared a migration guide.

If you discover any bugs, would like to contribute, or have feature requests for googleads, feel free to let us know via the library’s issue tracker. If you have any questions or feedback for us, you can reach us on the Google Ads Developers Google+ page.

- Mark Saniscalchi, Ads Developer Relations Team