Google Data

Reporting is an integral part of most AdWords API applications. To help you create and manage reports related to your AdWords campaigns, we introduced the ReportDefinitionService in the v201003 version of the AdWords API. In this post, we’ll cover th…

Authorization tokens were introduced with v2009 as part of the authorization mechanism adopted for the new version, ClientLogin. This new approach allows us to separate authorization from API requests, making it a two step process: first retrieve a tok…

Back in May, we announced the new “broad match modifier” in AdWords, which lets you create keywords with more reach than phrase match and more control than broad match. For now, this feature is only available in the UK and Canada, but it will be ro…

One of the ways that we ensure reliable access to the AdWords API system is to enforce a queries per second (QPS) limit. This limit is in place to prevent out-of-control or malicious software from overwhelming the API servers with requests and causing…

Back in 2007, we first introduced support for video ads (Click-to-Play Video) in the AdWords API. This required a dedicated VideoAd type, which made it less adaptive to future video formats. The AdWords API has significantly improved since then with …

Part of managing an AdWords account is cleaning out old or non-performing items, such as unused ad groups or low search volume keywords. Not all entities are deleted in the same way however, and the different methods are outlined below.Use the SET ope…

We’ll be performing routine system maintenance on Saturday, June 12 from approximately 10:00am to 2:00pm PDT. You won’t be able to access AdWords or the API during this time frame, but your ads will continue to run as normal. Best,- Eric Koleda, AdW…

Today we’re releasing a new version of the AdWords API: v201003 beta. This version contains many requested features, including: a ReportService beta, Ad Sitelinks, and bid simulator. We know many of you just migrated to v200909, so don’t worry, you…

The Sandbox Account Viewer is a sample application that demonstrates how to use the AdWords API client library to display contents of an AdWords sandbox account. It can be used to visualize the effects of a request on your account and to retrieve infor…

We’ll be performing routine system maintenance on Thursday, May 13th from approximately 6:00pm to 6:30pm PDT. You won’t be able to access AdWords or the API during this time frame, but your ads will continue to run as normal. While, AdWords system ma…

We’ll be performing routine system maintenance on Saturday, May 8th from approximately 10:00am to 2:00pm PDT. You won’t be able to access AdWords or the API during this time frame, but your ads will continue to run as normal. Best,- Eric Koleda, AdW…

In our previous blog post, we discussed how v2009 error handling works in synchronous APIs. In this blog post, we cover asynchronous error handling in BulkMutateJobService. If you are new to BulkMutateJobService, check out our introductory blog post and code.google.com article.

Due to its asynchronous nature, error handling in BulkMutateJobService is slightly different than in other services. Instead of throwing an ApiError object, BulkMutateJobService returns FailureResult or BatchFailureResult objects as its operation results. These objects in turn contain the relevant ApiErrors. BulkMutateJobService processes the operations within an operation stream in multiple atomic batches. If there is even one faulty operation in a batch, it causes the other non-faulty operations in the batch to fail as well. When a batch of n operations fails, you will get one FailureResult and n – 1 BatchFailureResults as results for the failed batch of operations. The FailureResult object will always be first in the batch, and will contain one ApiException object. The ApiException contains all the errors for the entire batch of operations, just like for other services. This will be followed by n – 1 BatchFailureResults, which can be viewed as placeholders, one for each operation in the batch.

For instance, assume that you are trying to create the following 9 text ads in a single OperationStream. For the purposes of this example, assume that the system processes operations in batches of 3. The errors are highlighted in red.

When BulkMutateJobService processes these operations, it will return the following results:

Result[0]: FailureResult.
 ApiException.errors has one ApiError
   PolicyViolationError @ operations[2].operand.ad.description2
Result[1]: BatchFailureResult, operationIndexInBatch = 1
Result[2]: BatchFailureResult, operationIndexInBatch = 2

Result[3]: FailureResult.
 ApiException.errors have 1 ApiError
   AdError.URL_NO_SCHEME @ operations[0].operand.ad.url
Result[4]: BatchFailureResult, operationIndexInBatch = 1
Result[5]: BatchFailureResult, operationIndexInBatch = 2

Result[6]: ReturnValueResult, successfully created Ad.
Result[7]: ReturnValueResult, successfully created Ad.
Result[8]: ReturnValueResult, successfully created Ad.

As shown in the results above, there is a 1:1 correspondence between the number of operations and number of results. You can get the successful operations by scanning the return value for results which are not FailureResult or BatchFailureResult (operations 6, 7 and 8 in this case). Then, scan through the results to locate FailureResult objects (which always appear at the beginning of the failed batch) to get the operation that actually failed (operations 2 and 3 in this case). You can now pick the failed operations that do not correspond to the ones obtained from FailureResult, and make a new job for them (0, 1, 4, 5). Note that the OGNL path in FailureResult is relative to the batch and not the operationstream, so you have to offset it by the index of FailureResult to get the failed operation (e.g. Results[3] is a FailureResult and its OGNL path is operations[0].operand.ad.url, so the failing operator in the original list is 3 + 0 = operations[3]).

A BulkMutateJob may also return the following error results, even though they’re not common:

LostResult: This happens when BMJS has lost results for some of a job’s operations. You can recover from this error by checking numFailedOperations and numUnprocessedOperations for the job. If both are zero, or if the number of errors in ApiError matches numFailedOperations, then the operations were successful, but the results are missing. In any other case, you have to retrieve the entities that were targeted by the operations and see if the operation actually succeeded or not.

UnprocessedResult: This indicates that the mutate operation was not processed. This could happen because the workflow implementation prevented the operation from being processed (e.g. the operations exceed API quota). You can recover from this issue by checking the job status, making sure that you have sufficient API quota left, and simply retrying the operations in a new job.

In an upcoming blog post, we will cover the most common errors you may get in v2009, and how to address them. We’ve included support for error handling in all of our client libraries to help get you started, so please try it out and share your feedback with us on the forum or the projects’ issue trackers.

– Anash P. Oommen, AdWords API Team

Today, we’re announcing preferred AdWords API pricing for agencies and developers of search engine marketing (SEM) tools. With preferred pricing, this important group of developers will get free API units based on managed client spend.As an agency or a…

You might remember that six months ago we announced that on April 22, 2010 we would be sunsetting many v13 services. Since then, we’ve posted reminders over the last 100 days right here on the blog. It’s finally April 22, so today we’re sunsetti…

As with any programming system, error handling is a critical part of the AdWords API as well. In v13, we used to describe every error by its own error code. While this was simple and handy, the API provided less additional information about the error i…