Holiday reminder about IDs

Whether you recently updated your code or just started with the AdWords API, please keep in mind that IDs of all entities are represented as xsd:long (64 bit signed integer) values. It is important to note that if your code stores ID values in a data type with lower range, the value may suffer from integer overflow.

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

-- Stan Grinberg, AdWords API Team

Dive deeper with the reference documentation sidebar

There are a wide variety of resources available for those learning about the AdWords API, but since they’re spread out across multiple sites it’s not always easy to find the information you’re looking for. While we acknowledge the need for these multiple sources, we knew we could do more to bring together our content from Blogger, YouTube, Google Code, and Twitter. We saw the official reference documentation as a good home for the information, and so we’ve added a new sidebar to the service-level pages that displays related material.

The code examples are pulled from our client libraries, and they provide concrete examples of the services in action. The blog posts are pulled from this blog, and contain deep dives into the services, explaining the behaviors and use cases they are suited for. The videos are pulled from our YouTube playlist, and feature recordings from our developer workshops across the world. The tweets are pulled from our @adwordsapi account, and often contain short tips on how to use the services more efficiently.

The sidebar uses the Google Feeds API to pull data from our multiple repositories, meaning that new content will be automatically displayed as soon as it becomes available. We hope that this sidebar leads to more efficient and effective development against the AdWords API, and if you have feedback or further ideas please reach out to us on the forum.

- Eric Koleda, AdWords API Team

Even more dynamic ads: Announcing Ad parameters enhancements

After we launched version v2009 of the AdWords API we announced the addition of a new feature called Ad parameters. Since then, many of you have used Ad parameters to insert dynamic numeric values into your text ads while retaining the ads’ historical performance information. We’ve heard feedback from you about functionality you’d like to see included in Ad parameters so we've released some enhancements to the feature.

Here’s what’s new:

• You can now dynamically insert the percent sign (%) for values that include percentage discounts such as “Mobile Phone Accessories Now 20% Off”
• We’ve added support for additional currency symbols and codes so you can include the currency symbol in the dynamic parameter to create ad text like “Flights to London Starting at €250”
• You’re now able to use the forward slash character (/) for dynamic replacements with fraction discounts like “1/2 Off Our Entire Inventory Only This Weekend”
• The plus (+) and minus (-) signs are now supported so you can advertise “NASDAQ +20 Points Today, Speak With a Broker Now.”

We hope these enhancements enable you to create even more dynamic ads with Ad parameters. Please continue to share your feedback and questions with us on the developer forum.

--Jason Shafton, Product Marketing Manager

Harness the power of predicates in your reports

The reporting services of the AdWords API are designed to allow you to download large amounts of data, but it can often be useful to filter out certain rows from the start to cut down on processing and transfer time. DefinedReportJobs created using the v13 ReportService supported a limited set of filtering options, primarily on IDs and statuses. Filtering on a more complex set of criteria would require post processing the report client-side. The ReportDefinitionService introduced in v201003 supports Predicates, a more flexible system of filters that can be used to create very targeted reports.

A predicate is composed of three parts: the field, the operator, and the values. Predicates can be created for almost every field available, indicated by canFilter set to "true" in the results returned from getReportFields().

<rval>
<fieldName>Clicks</fieldName>
<displayFieldName>Clicks</displayFieldName>
<xmlAttributeName>clicks</xmlAttributeName>
<fieldType>Long</fieldType>
<canSelect>true</canSelect>
<canFilter>true</canFilter>
</rval>

There are a fixed set of operators that can be used to compare the value of the field selected. EQUALS can be used to filter for an exact match, while IN can be used to match any of a set of values. GREATER_THAN and LESS_THAN are available for comparing numerical values, and CONTAINS is useful when working with strings. Only one operator can be used per predicate, but multiple predicates can be created for the same field to create more complex logic.

The values used in the predicate depend heavily on the field being operated on. Numerical values should be used for Long, Double, and Integer fields, and arbitrary strings can be used for String fields. The values for Money and Bid fields must always be specified in micros, even if the report is eventually downloaded with whole currency amounts. Although percentage fields like Ctr are returned as whole numbers, the values used in predicates should be the decimal equivalents. Predicates on Enum fields must only use the values of the enum, as outlined in the documentation and in the enumValues property returned by getReportFields().

<rval>
<fieldName>CampaignStatus</fieldName>
<displayFieldName>Campaign state</displayFieldName>
<xmlAttributeName>campaignState</xmlAttributeName>
<fieldType>CampaignStatus</fieldType>
<enumValues>ACTIVE</enumValues>
<enumValues>DELETED</enumValues>
<enumValues>PAUSED</enumValues>
<canSelect>true</canSelect>
<canFilter>true</canFilter>
</rval>

If multiple predicates are used within a Selector they will be combined using AND logic, so that the resulting report will only contain rows that satisfies all of the predicates. It’s not possible to combine predicates using OR logic at this time, but some common use cases can be handled using a single predicate and the IN operator. For example, to match keywords with either the PHRASE or EXACT match type you could use the following predicate:

<predicates>
<field>KeywordMatchType</field>
<operator>IN</operator>
<values>PHRASE</values>
<values>EXACT</values>
</predicates>

When combined together, predicates can be quite powerful. Consider the following example: I own an electronics shop that is starting to sell a wider array of tablet computers, and I want to drive more traffic to that section of my website. I’d like to start by finding all my current keywords that include the word "tablet" and have a high CTR, and then use them to generate new keyword ideas using the TargetingIdeaService. I’m only interested in keywords with greater than a 10% CTR, that have at least 100 impressions, and that are in enabled or paused ad groups.

Using predicates I can create a KEYWORDS_PERFORMANCE_REPORT that only returns me the exact data I am interested in:

<predicates>
<field>CampaignId</field>
<operator>EQUALS</operator>
<values>123456789</values>
</predicates>
<predicates>
<field>AdGroupStatus</field>
<operator>IN</operator>
<values>ENABLED</values>
<values>PAUSED</values>
</predicates>
<predicates>
<field>KeywordText</field>
<operator>CONTAINS</operator>
<values>tablet</values>
</predicates>
<predicates>
<field>Ctr</field>
<operator>GREATER_THAN</operator>
<values>0.10</values>
</predicates>
<predicates>
<field>Impressions</field>
<operator>GREATER_THAN_EQUALS</operator>
<values>100</values>
</predicates>

Predicates are one of many new improvements introduced in the ReportDefinitionService, and if you aren’t using the service yet, now is a great time to start looking into migrating. The service is fully supported in all our client libraries, and we’re available on the forum to answer any questions you may have.

- Eric Koleda, AdWords API Team

Discover v201008: Partial Failure for AdGroupCriterionService

With v201008 of the AdWords API we have introduced a new beta feature for AdGroupCriterionService: Partial Failure. Typically all requests to the AdWords API are atomic, so each of them either fails or succeeds in full. While this can be helpful to maintain consistency, we’ve heard from you that, in some cases, you would prefer that some operations fail while other changes are applied.

AdGroupCriterionService requests often contain many Criteria to add or update. Having an error in just one of them will force you to resend the whole set of objects again. We’ve introduced Partial Failure to enable you to get back a list of failed and successful operations and retry the failed ones only.

To utilize the new feature you’ll need to set this extra SOAP header:

partialFailure = true

Here’s an example from the Java client library:

// usual initialization code
AdWordsUser user = new AdWordsUser();
// Enable partial failure
user.setUsePartialFailure(true);
// Get the AdGroupCriterionService
AdGroupCriterionServiceInterface adGroupCriterionService =
  user.getService(AdWordsService.V201008.ADGROUP_CRITERION_SERVICE);
// Set up operations and operands here
List<AdGroupCriterionOperation> operations = new ArrayList<AdGroupCriterionOperation>();
// [...]

// Execute operations (add ad group criteria)
AdGroupCriterionReturnValue result =
  adGroupCriterionService.mutate(operations.toArray(
      new AdGroupCriterionOperation[] {}));

Now processing succeeded results:

// Display results
if ((result != null) && (result.getValue() != null)) {
  // A result is returned for every operation requested
  for (AdGroupCriterion adGroupCriterionResult : result.getValue()) {
    // Successful operation result will contain a non-null Criterion
    if (adGroupCriterionResult.getCriterion() != null) {
      System.out.printf("Ad group criterion with ad group id '%d', and " +
          "criterion id '%d', and keyword '%s' was added.\n",
          adGroupCriterionResult.getAdGroupId(),
          adGroupCriterionResult.getCriterion().getId(),
          ((Keyword) adGroupCriterionResult.getCriterion()).getText());
    }
  }
} else {
  System.out.println("No ad group criteria were added.");
}

Here is how to handle the failed operations:

// Is there any Partial Failure errors in the results?
if ((result != null) && (result.getPartialFailureErrors() != null)) {
  // Retrieving ApiError object for each of failures
  for (ApiError apiError : result.getPartialFailureErrors()) {
    // The order of the fields might be different to the order of operations in the
    // request, so we are getting the corresponding operation index from the fieldPath.
    Matcher matcher = operationIndexPattern.matcher(apiError.getFieldPath());
    if (matcher.matches()) {
      int operationIndex = Integer.parseInt(matcher.group(1));
      AdGroupCriterion adGroupCriterion =
          operations.get(operationIndex).getOperand();
      System.out.printf("Ad group criterion with ad group id '%d' and " +
          "keyword '%s' triggered a failure for the following reason: '%s'.\n",
          adGroupCriterion.getAdGroupId(),
          ((Keyword) adGroupCriterion.getCriterion()).getText(),
          apiError.getErrorString());
    } else {
      System.out.printf(
          "A failure for the following reason: '%s' has occurred.\n",
          apiError.getErrorString());
    }
  }
}

Partial Failure is fully supported in our client libraries. If you have any questions please post them on the AdWords API forum. This topic is also covered in a video presentation.

-- Danial Klimkin, AdWords API Team.