Location targeting update in AdWords

In February, we launched city targeting in additional 17 countries, and our goal is to make location targeting more accurate, easy to use, and flexible. As part of planning for future improvements, we’re making several changes to the AdWords location targeting capabilities that will affect the way you operate with the API. These changes will start occurring after July 8, 2011 and include:

• Changes to existing available locations: Due to changes in real-world geography or the existence of duplicate or overlapping location targets, we’re removing certain location targets in countries such as Japan, Denmark, Spain, and the Netherlands, among others. For example, in 2010, six provinces were abolished in Finland, and while you’ll no longer be able to target these provinces, you can continue targeting cities in Finland. You won’t be able to target these provinces through the API and UI, but you’ll be able to continue targeting cities in Finland. After the changes take effect, you won't be able to add the locations that are listed here to new campaigns. If you're currently targeting any of these locations in your existing campaigns, you should migrate them to the recommended targets in the list. Otherwise, we'll migrate them automatically. Please review the list carefully since some of these changes will result in migration to larger locations. After this change takes place, if you try to use any of these locations you’ll receive a TargetError.TARGETING_NOT_SUPPORTED from the API.

• Sunset of PolygonTarget: You will no longer be able to add PolygonTargets through the API. You’ll still be able to retrieve and delete existing ones in your current campaigns. Any existing polygon target will continue to be used until the end of 2011. After that, all polygon targets that are still present in your AdWords campaigns will be migrated to other GeoTargets such as a city close to your polygon target or to specific ProximityTargets. We encourage you to replace your polygon targets to city, metro, province, country or proximity targets or we will migrate them automatically at end of 2011.

• Removal of allowServiceOfAddress in ProximityTargets: In some countries, you have the option to use the address in a ProximityTarget to show with your ads by setting allowServiceOfAddress. This field will no longer be available in future API releases and ignored when used in current versions. If you want to display your business address or phone number, you will need to use AdWords location extensions.

These changes will take place after July 8, 2011 and we recommend you adjusting your applications before. We also recommend that you adjust the location targeting settings of your campaigns immediately with the available alternatives.

  David Torres, AdWords API Team

Impact of new optional-login accounts on the AdWords API

We recently changed the workflow for creating a new client account within an MCC. Until now, all new accounts were required to have a unique email address and password from the onset, but going forward that step will be optional. For AdWords users that rely on an MCC account to access their clients, this provides a more secure, scalable experience. However, API developers will need to consider how this impacts the way they access and manage accounts in their custom applications.

All AdWords accounts will continue to have a unique numerical customer ID, as well as a “descriptive name” field. Any account that already has a login email will continue to function normally, and you can invite a new unique login email to any account (regardless of how it was created) if necessary.

Here are some ways that your API application might rely on login emails:

• If you use login emails as unique identifiers in your database or UI
• If you use the <clientEmail> header instead of the <clientCustomerId> header
• If you request Auth tokens at the client level as opposed to the MCC level
• If you filter calls to the InfoService by login email; it does not yet support filtering by customer ID
• If you use v13’s AccountService.getClientAccounts() call, which returns an array of login emails, you should explore switching to v201101’s ServicedAccountService.get() call, which includes the customer ID in the return value.

In short, the safest thing is to make sure your application does not assume the existence of a login email for any client accounts that you manage via MCC. For more information on optional-login accounts, visit the AdWords Help Center on this topic.

-Aaron Karp, AdWords API Team

Update on AdWords API v201101 sunset dates

We recently launched AdWords API v201101, including details on the deprecation timeline for previous versions.

We would like to clarify the sunset dates for the following versions and services:

• API v13 TrafficEstimatorService: we’re making changes to the TrafficEstimatorService algorithm in v201101 and v201008 to bring you more accurate estimates. We will therefore be sunsetting API v13 TrafficEstimatorService on June 30, 2011. See more on updates to the traffic estimates algorithm on the Inside AdWords Blog.

• API v200909, v201003, v201008, and API v13 ReportService - the sunset date will be four months from when MCC cross-client reports go live. We will post to this blog as soon as MCC cross-client reports becomes available.

For help migrating to v201101, review the resources on the AdWords API code site, including release notes and AdWords API client libraries. If you have any questions please post them on the AdWords API forum.

UPDATE as of Jul 14, 2011

We want to clarify that the sunset that will happen four months from when MCC cross-client reports go live will include ALL services in the following versions:

• v200909
• v201003
• v201008

In addition to v13 ReportService.

The ONLY functional services remaining will be:

• All v201101 services
• v13 AccountService

Posted by Katie Miller, AdWords API Team

Conversion Tracking in v201101

With the release of v201101 we introduce the ConversionTrackerService to manage conversion tracking via the AdWords API. This new service lets you create, retrieve, modify and remove AdWordsConversionTracker objects, which hold all the information about a specific conversion type that resides in your account, including ID, name, status, category, and others, but more importantly the conversion code snippet you need to put on your website in order to fully implement conversion tracking. The main objective of this post is to show the basic operations that can be performed by using this service.

Creation

Let’s start by creating a "PURCHASE" AdWordsConversionTracker that specifies the one line site stats logo, HTML markup in the code snippet, and that your website is using HTTPS:


// Create AdWords conversion.
AdWordsConversionTracker adWordsConversionTracker =
    new AdWordsConversionTracker();
adWordsConversionTracker.setName("A purchase conversion tracker");
adWordsConversionTracker.setCategory(ConversionTrackerCategory.PURCHASE);
adWordsConversionTracker.setMarkupLanguage(
    AdWordsConversionTrackerMarkupLanguage.HTML);
adWordsConversionTracker.setHttpProtocol(
    AdWordsConversionTrackerHttpProtocol.HTTPS);
adWordsConversionTracker.setTextFormat(
    AdWordsConversionTrackerTextFormat.ONE_LINE);
adWordsConversionTracker.setUserRevenueValue("<%= shoppingCartTotal %>");

// Create operations.
ConversionTrackerOperation operation = new ConversionTrackerOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(adWordsConversionTracker);
ConversionTrackerOperation[] operations =
    new ConversionTrackerOperation[] {operation};
// Add conversion tracker.
conversionTrackerService.mutate(operations);


AdWordsConversionTracker offers a set of properties that control what the conversion code snippet will look like. Let’s go over some of them:

markupLanguage: Determines the markup language of the code snippet. In most cases this will be HTML but CHTML, XHTML and WML are also supported, mostly for mobile devices that are not fully HTML capable.

httpProtocol: The protocol used by your web page, either HTTP or HTTPS. If this setting is incorrectly specified your visitors will experience warnings like "Page includes other resources which are not secure".

textFormat, conversionPageLanguage and backgroundColor: We encourage you to use visible text for conversion tracking when using AdWords conversion tracking technology. For this purpose two textFormat options are offered: ONE_LINE and TWO_LINE. conversionPageLanguage and backgroundColor control the language in which the text will be displayed and what background color will be used, respectively. If you decide to not use Google's site logo, you can specify HIDDEN for the textFormat. In this case, setting conversionPageLanguage and backgroundColor has no effects.

userRevenueValue: This value can be either fixed or dynamically set. For specific examples on how to set this value based on your server-side technology refer to the AdWords Conversion Tracking Setup Guide. Examples of its use would be a user shopping cart total value for a "PURCHASE" conversion or a fixed weight value you give to a specific "LEAD" conversion. This value is only meaningful to you in reports and it has no effect in AdWords costs. The conversion values can then be reported back to you using the reporting capabilities of the API by including fields such as ConversionValue in your reports.

Retrieval

As with most of our services, ConversionTrackerService offers a get method for you to retrieve ConversionTracker objects. This operation is based on generic selectors, so you can filter, sort and paginate results as desired.

The following example shows you how to retrieve the Id, Name and Category of all your ConversionTracker objects.


// Create selector.
Selector selector = new Selector();
selector.setFields(new String[] {"Name", "Status", "Category"});
selector.setOrdering(new OrderBy[] {new OrderBy("Name",
    SortOrder.ASCENDING)});

// Get all conversion trackers.
ConversionTrackerPage page = service.get(selector);

// Display conversion trackers.
if (page != null && page.getEntries() != null) {
  for (ConversionTracker conversionTracker : page.getEntries()) {
    if (conversionTracker instanceof AdWordsConversionTracker) {
      AdWordsConversionTracker awConversionTracker =
          (AdWordsConversionTracker) conversionTracker;
      System.out.printf("Conversion tracker with id \"%d\", " +
          "name \"%s\", status \"%s\", category \"%s\" and " +
          "snippet \"%s\" was found.\n", awConversionTracker.getId(),
          awConversionTracker.getName(),
          awConversionTracker.getStatus(),
          awConversionTracker.getCategory(),
          awConversionTracker.getSnippet());
    }
  }
}


Notice that even though the Snippet field was not requested in the selector, it will always be returned in your results. It contains the code you need to put in your web page to start capturing conversions. We recommend that you put this code as close as possible to the footer of the page.

Update

As you can create and retrieve ConversionTracker objects, it is also possible to update most of their properties using the service mutate operation. One of the most common operations is to disable a conversion tracker, hence stop capturing conversions even if the code snippet still resides in your website. The following code shows how to disable a conversion tracker.


long conversionId =
    Long.parseLong("CONVERSION_ID_YOU_WANT_TO_DISABLE");

// Create conversion tracker with updated status and name.
AdWordsConversionTracker adWordsConversionTracker =
    new AdWordsConversionTracker();
adWordsConversionTracker.setId(conversionId);
adWordsConversionTracker.setStatus(ConversionTrackerStatus.DISABLED);

// Create operations.
ConversionTrackerOperation operation = 
    new ConversionTrackerOperation();
operation.setOperand(adWordsConversionTracker);
operation.setOperator(Operator.SET);

ConversionTrackerOperation[] operations =
    new ConversionTrackerOperation[] {operation};

// Update conversion tracker.
ConversionTrackerReturnValue result = service.mutate(operations);


Reports

Most of the API reports contain conversion fields such as Conversions, ConversionValue, CostPerConversion, and others that you can query. Two conversion fields that allow you to segment conversion stats in your report are ConversionCategoryName and ConversionTypeName. Use ConversionCategoryName to group by conversion category (i.e., PURCHASE, LEAD, ...) and ConversionTypeName to group by ConversionTracker name, which is unique for each account. Keep in mind these two fields cannot be combined with non-conversion fields such as Impressions or Clicks.

User lists and conversions

A special mention goes to RemarketingUserList objects which are managed via the UserListService. This kind of list has a close relationship with conversions since every list is associated with at least one AdWords ConversionTracker. To retrieve the associated ConversionTracker objects, a RemarketingUserList contains a list of UserListConversionType objects which hold the IDs of the associated conversion trackers. Hence you can use those IDs to get, via the ConversionTrackerService, the code snippets required to fully enable your remarketing list. To learn more about user lists and remarketing in the AdWords API read the post on Remarketing.

All code examples in this post were developed using the AdWords API Java Client Library, but we also offer support for other popular languages. To learn more about our client libraries, visit our code site. As always, feel free to contact us via the AdWords API Forum.

  David Torres, AdWords API Team