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

Tuesday, April 26, 2011

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.


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(); = campaignId;

// Set GeoTargetType.
GeoTargetTypeSetting geoSetting = new GeoTargetTypeSetting();
geoSetting.positiveGeoTargetType =
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 =
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

Monday, April 18, 2011

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

Monday, April 11, 2011

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

AdWords Position Preference feature is being retired

Tuesday, April 05, 2011

As part of the retirement of the Position Preference bidding feature, this feature can no longer be enabled via the AdWords API.

Starting tomorrow, calling CampaignService with BiddingStrategy ManualCPC.PositionPreference set to ON will return the error
This feature can still be used, however, to disable Position preference for a campaign.

Then, starting in May, the PositionPreference field will be disabled entirely, meaning that calling CampaignService with BiddingStrategy ManualCPC.PositionPreference set to any value will return the error BiddingError.POSITION_PREFERENCE_NOT_ENABLED. This change is timed to coincide with the removal of the feature from the AdWords web interface.

We appreciate your understanding and your continued support of AdWords.

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

Posted by Stan Grinberg, AdWords API Team

Opportunities tab optimization ideas now available through the AdWords API (beta)

Monday, April 04, 2011

The Opportunities tab in AdWords can help you find keyword, bid, and budget ideas for your account. With each optimization idea, you’ll also see estimates for how the idea might affect your impressions, clicks, and cost. Until now, you had to log in to AdWords to view these custom optimization ideas. Now you can discover and use ideas from the Opportunities tab with the AdWords API.

This functionality is exposed using the new BulkOpportunityService. The BulkOpportunityService returns new keyword ideas that may help you capture more impressions and clicks, budget ideas that may help you get additional traffic for campaigns that are meeting their budgets, and bid ideas that may help you increase or decrease CPC bids to increase traffic or reduce costs.

Extend your current API tools with BulkOpportunityService
If you use the Adwords API to build tools to manage your complex or large AdWords account, you can now extend your tools to surface or use the ideas returned by the BulkOpportunityService. 

Your tools can display these ideas where they’re relevant. For example:
  • If you have a tool that allows the modification of keywords in an ad group, you might display the keyword ideas returned by the BulkOpportunityService as ideas for that ad group.
  • If you use a tool that allows changes to bids or budgets, you might also use bid ideas or budget ideas respectively and see the potential impact of those changes.
Make BulkOpportunityService calls for free during the beta period
Calling the BulkOpportunityService with a selector and a paging value, both specified in the BulkOpportunitySelector, will return a number of OpportunityIdeas that you can review and decide to accept or ignore on a case-by-case basis. For some examples on how to do this, look at the code samples provided with the client libraries.

If you want to make changes based on ideas you retrieved using the BulkOpportunityService, you can make these changes through existing Campaign Management services such as AdGroupService, CampaignService, etc.

We’ll be introducing the BulkOpportunityService as a beta over the next several days. Calls made to the service will be free during this beta period. We’ll post again to this blog when we are out of the beta period and will start charging.

After you’ve tried the BulkOpportunityService, please share your feedback and experiences on the API and the client libraries at the AdWords API Forum.

Posted by Umesh Unnikrisnan, Product Manager, AdWords