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

Discover v201101 - Advanced geo-targeting using Location of Presence or Area of Interest

AdWords allows you to target your users based on their Location of Presence (LOP) or Area of Interest (AOI). This feature is now available to developers through AdWords API v201101 and this blog post discusses how to use this new AdWords API feature.

This blog post assumes that are familiar with how to set geographic targets on your campaign. If not, you can learn more here. For a refresher on where regionally targeted ads appear, you can refer to the AdWords Help Center article here.

Introduction

To understand how LOP or AOI based geo-targeting works, consider the following example:

You own a flower shop in New York. You run a campaign that targets New York, and one of your keywords is “flowers”. The following table shows how Google serves ads if you use LOP and AOI settings.

Target Method	User Location (LOP)	User Query	User’s Area of Interest (AOI)	User sees Ad
LOP only	New York	flowers
	California	flowers in New York	New York
AOI only	New York	flowers
	California	flowers in New York	New York
LOP and AOI	New York	flowers
	California	flowers in New York	New York

You can get or set LOP and AOI based geo-targeting through the settings field of your campaign using the GeoTargetTypeSetting class. The following C# code snippet shows how to set AOI based geo-targeting for your campaign.

long campaignId = long.Parse(_T("INSERT_CAMPAIGN_ID_HERE"));

// Create campaign with updated budget.
Campaign campaign = new Campaign();
campaign.id = campaignId;

// Set GeoTargetType.
GeoTargetTypeSetting geoSetting = new GeoTargetTypeSetting();
geoSetting.positiveGeoTargetType =
GeoTargetTypeSettingPositiveGeoTargetType.AREA_OF_INTEREST;
campaign.settings = new Setting[] {geoSetting};

// Create operation.
CampaignOperation operation = new CampaignOperation();
operation.@operator = Operator.SET;
operation.operand = campaign;

// Update campaign.
CampaignReturnValue retVal = campaignService.mutate((new CampaignOperation[] {operation}));

GeoTargetTypeSetting can also be used to geo-target negatively. You can do negative geo-targeting based on LOP alone, or both LOP and AOI. To understand how negative GeoTargetTypeSetting works, consider the following modified version of the previous example:

You run a campaign that targets all of the US, but excludes New York, and one of your keywords is “flowers”. The following table shows how Google serves ads based on your settings.

Target Method	User Location (LOP)	User Query	User’s Area of Interest (AOI)	User sees Ad
LOP only	New York	flowers
	California	flowers in New York	New York
	Texas	flowers
LOP and AOI	New York	flowers
	California	flowers in New York	New York
	Texas	flowers

The following code snippet shows how to apply negative GeoTargetTypeSetting based on LOP:

// Set GeoTargetType.
GeoTargetTypeSetting geoSetting = new GeoTargetTypeSetting();
geoSetting.negativeGeoTargetType =
GeoTargetTypeSettingNegativeGeoTargetType.LOCATION_OF_PRESENCE;
campaign.settings = new Setting[] {geoSetting};

A few points worth noting about GeoTargetTypeSetting:

• This setting applies only to ads targeting the Google Search Network, and does not affect ads targeting the Google Display Network.
• This setting applies only within a country where we determine the user is physically located based on their device location (such as an IP address). For example, if you have targeted New York for your ads, then the ad would not show for a user in London searching for flowers in New York.
• Even if you have a negative LOP based targeting for a certain area, your campaign's geographic reports may still show impressions from your excluded area. This is because we report a physical location for users whose search didn't include a location of interest, and we generally report the user's location of search intent if their search includes one.

We have added support for LOP and AOI based geotargetting in all of our client libraries, so please take advantage of this new feature and share your feedback with us on the forum.

  --Anash P. Oommen, AdWords API Team

Use reports to download large data sets

In this post, we will share best practices for downloading large data sets. Specifically, we will outline how to accomplish this using reports and why this is more efficient than paging with selectors.

When you request a large amount of data using generic selectors (for example, keywords), you may find that the responses are slow for very large data sets. First, we advise you not to page past 10,000 records due to the increased amount of time it takes to skip the first 10,000 records. Second, as a rule of thumb, once you exceed 100,000 keywords, it is a good idea to use a report to obtain your data rather than generic selectors.

Reports are designed to handle large quantities of data. In addition, you will also use fewer API units if you request data via reports than if you request the same data via the AdGroupCriterionService. For example, say you would like to obtain all the keywords across all ad groups using paging of 1000 for 100,000 total keywords. This would require 100,000 API units, one per AdGroupCriterion. Defining a report and downloading the data that way will cost significantly less units in the long run. If you define the report with a sliding date range such as TODAY or LAST_WEEK, you can reuse the report each time you need to download your data set. Please see this page for more information about reports.

If you need fields that are not available in reports, you still have some options to increase performance. With generic selectors you can specify only the fields you need; the fewer the number of requested fields, the faster the results will be returned. You can also use predicates to filter and limit the amount of data in each result set. By requesting keywords on a per-campaign or per-ad group basis instead of all at once, you may actually get your results faster.

If you have any questions about using reports with the API, you can ask us on the forum.

- Kevin Winter, AdWords API Team

Experiment with ads in v201101

When introduced last year, AdWords Campaign Experiments (ACE) allowed for experimental changes to be applied to ad groups and criteria. To allow for even greater flexibility, in v201101 we’ve added the ability to apply experimental changes to individual ads as well. Just like other entities, experiment data can be added to an AdGroupAd to indicates its status in the experiment. For example, the following code can be used to add an existing ad to the experimental split.

// Create ad using an existing ID.
$ad = new Ad();
$ad->id = $adId;

// Create ad group ad.
$adGroupAd = new AdGroupAd();
$adGroupAd->adGroupId = $adGroupId;
$adGroupAd->ad = $ad;
$adGroupAd->status = 'ENABLED';

// Create experiment data for experiment-only split.
$experimentData = new AdGroupAdExperimentData();
$experimentData->experimentId = $experimentId;
$experimentData->experimentDeltaStatus = 'EXPERIMENT_ONLY';
$adGroupAd->experimentData = $experimentData;

// Create operation.
$operation = new AdGroupAdOperation();
$operation->operator = 'SET';
$operation->operand = $adGroupAd;
$operations = array($operation);

// Update ad.
$result = $adGroupAdService->mutate($operations);

Experiment data can only be used to include or exclude an ad from an experiment; all other properties of the ad will remain the same. If you have any questions about setting up experiments with the API you can ask us on the forum.

- Eric Koleda, AdWords API Team