Discover v2009: Setting ad parameters with the AdParamService

Wednesday, November 25, 2009

In a blog post yesterday we introduced ad parameters, a new AdWords feature that allows for dynamic insertion of numeric and currency values into ads while retaining ad history. To manage ad parameters, a new service was added to the v200909 API: the AdParamService.

In the example introduced earlier, you own a business selling antique cups that wants to add price and inventory information to your ads. To leverage ad parameters you create a text ad like:

and you configure the following ad parameters on your keywords:

antique cups

A user searching for "antique cups" would will see the following ad text:

Text ads, even those with ad parameter placeholders, can be created using the normal methods of the AdGroupAdService. The AdParamService is only used for setting ad parameter values on keywords. This service allows for the getting and setting of AdParam objects, which contain the ad group ID and criterion ID for the target keyword, the insertion text, and the parameter index.

For example, to set the ad parameters for "antique cups" we would use the following PHP code (using the AdWords API PHP Client Library):
$adParam1 = new AdParam($adGroupId, $criterionId, '$80', 1);
$adParam2 = new AdParam($adGroupId, $criterionId, '18', 2);

$operation1 = new AdParamOperation($adParam1, 'SET');
$operation2 = new AdParamOperation($adParam2, 'SET');

$adParams = $adParamService->mutate(array($operation1, $operation2));
Existing ad params can be selected by ad group ID or by ad group ID and criterion ID. To get the ad parameters set above we would run the following:
$selector = new AdParamSelector(array($adGroupId), array($criterionId));
$adParamPage = AdParamServiceTest::$service->get($selector);
Some key points to remember about the ad parameters and the AdParamService are:
  • Ad parameters are set on keywords, not ads.
  • Ad parameters can only accept numerical and currency values, but the default text of the placeholder in the ad can be any string.
  • The length of the default text in the placeholder contributes to the total length of the line in the ad, but the curly braces, parameters name, and colon do not.
  • Ad parameters are 1-based indexed, meaning the two parameters are "1" and "2".
  • The AdParamOperation should always use the "SET" operator, even when you are setting the parameters for the first time.
To help you get started, we've included support for this service in our client libraries. As always, we are here to answer your questions, collect feedback, and assist with migration to v2009 of the AdWords API.

More Dynamic Ads with Ad parameters

Tuesday, November 24, 2009

We're excited to announce that a new feature of the v2009 API, called Ad parameters, is now available. Ad parameters enable you to change numeric information (for example: prices, discount percentages, etc.) within your text ad, while keeping the history and statistics associated with the ad.

Here's a hypothetical scenario illustrating how Ad parameters might help you make your ads more specific and appealing:

Let's say that you sell high-end antique tea cups on your website and it is important for you to qualify users before they even click on your ads. After running some tests, you have found that you can attract serious buyers to your website by including a starting price in your ads. You also want to include the number of varieties of tea cups you currently have in stock, to make your ad appear fresh.

You would like to update your ad text via the AdWords API in response to price and availability fluctuations within your inventory system, but you don't want to lose the statistics associated with your ad. Ad parameters can solve this problem for you.

With Ad parameters, you can specify an ad like this:

Notice that you can specify default values for param1 and param2 within the ad text. You need to set dynamic numeric values for param1 and param2 at the keyword level via the AdParamService of the v2009 API.

On a certain day, if your inventory of tea cups starts at $80 with 18 designs in stock, you can set these values for the relevant keywords within your ad group, as follows:

antique cups

A user searching for "antique cups" subsequently will see the following ad:

For more information on using Ad parameters, be sure to check out our Discover v2009 blog post on this topic (coming soon).

Finally, a few notes about this feature:
  • Ad parameters can only be updated via the AdWords API. Updates are not currently supported in AdWords Editor or in the AdWords interface
  • You can specify at most two parameters
  • While the default value of the parameters (specified within the ad text) can be non-numeric, the dynamic value of the parameters (specified via the AdWords API) must always be numeric. Currency symbols are allowed
  • As usual, your ads must comply with our AdWords Advertising Policies
-- Shreyas Doshi, Product Manager, AdWords API

Version v200906 beta will be shut down on February 2, 2010

Monday, November 23, 2009

The v200906 API, which we released as a limited beta in June 2009, will be shut down on February 2, 2010. The recently-launched v200909 API is a full replacement for v200906 and it adds substantial additional functionality. For most developers, the migration from v200906 to v200909 will be just a matter of updating the version in the namespace and re-compiling/building their application.

If you are using one of our client libraries, the changes required for migration will be as easy as

  • Java
    • Change import; to import;
    • Change CampaignServiceInterface campaignService = user.getService(AdWordsService.V200906.CAMPAIGN_SERVICE); to CampaignServiceInterface campaignService = user.getService(AdWordsService.V200909.CAMPAIGN_SERVICE);
  • DotNet
    • Change using; to using;
    • Change namespace to namespace
    • Change CampaignService service = (CampaignService) user.GetService(AdWordsService.v200906.CampaignService); to CampaignService service = (CampaignService) user.GetService(AdWordsService.v200909.CampaignService);
  • Python
    • Explicitly set version, campaign_service = client.GetCampaignService(version='v200909')
  • Ruby
    • Change campaign_srv = adwords.get_service('Campaign', 200906) to campaign_srv = adwords.get_service('Campaign', 200909)
  • Perl
    • Change version in types, Google::AdWords::v200906::Types::SomeType to Google::AdWords::v200909::Types::SomeType
  • PHP
    • Defaults to v200909

As always, the AdWords API team is available to help ensure a smooth transition to the new v200909 API. Feel free to post your questions on the forum. Finally, to learn about the exciting new features of v200909, we encourage you to check out the weekly posts in our Discover v2009 series.

--Stan Grinberg, AdWords API Team

AdWords Downtime: November 14th, 10am-2pm PDT

Tuesday, November 10, 2009

We'll be performing routine system maintenance on Saturday, November 14th 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.

-Eric Koleda, AdWords API Team

Discover v2009: Getting ideas with TargetingIdeaService

Tuesday, November 03, 2009

As we announced recently, KeywordToolService and SiteSuggestionService were among the services deprecated to make way for their v2009 successors. In designing their new replacement, we sought to create a unified experience similar to our other v2009 services. The new TargetingIdeaService combines queries for both keywords and placements into one service with a common method to retrieve TargetingIdeas. In this blog post, we will discuss querying the new service for ideas to aid you in shaping your campaign and how you would go about migrating from v13.

Similar to our other new services, the TargetingIdeaService uses a get method along with a selector to query for both keywords and placements. There are currently two types of requests that can be made - ideas and stats. We will discuss querying for ideas here and save stats for a future blog post.

There are 4 main parameters of the selector which are used for querying ideas:

  • requestType - the request type equal to IDEAS or STATS.
  • ideaType - the type of idea to get equal to KEYWORD or PLACEMENT.
  • searchParameters - contains both the seed parameters as well as filters to apply to the results, which are specific to the ideaType.
  • requestedAttributeTypes - narrows the attributes returned to only those requested, which are specific to the searchParameters and ideaType.

Using these 4 parameters, you will have a vast degree of customization for your results. Each of these parameters and their limitations is best described in the TargetingIdeaSelector documentation page. We will now walk through a few examples on how you would replicate v13's functionality, and how you can improve upon it with v2009.

Replicating KeywordToolService.getKeywordVariations

In v13, you would typically retrieve a list of keyword variations from the getKeywordVariations method. Below is a snippet of code which replicates the basic functionality of this method.

    Keyword keyword = new Keyword();
    keyword.setText("cheap airline tickets");

    LanguageTarget language = new LanguageTarget();

    CountryTarget country = new CountryTarget();

    TargetingIdeaSelector selector = new TargetingIdeaSelector();
    selector.setSearchParameters(new SearchParameter[] {
      new RelatedToKeywordSearchParameter(null, new Keyword[] {keyword}),
      new LanguageTargetSearchParameter(null, new LanguageTarget[] {language}),
      new CountryTargetSearchParameter(null, new CountryTarget[] {country})});
    selector.setPaging(new Paging(0, 6));

The results you get back may resemble keywords like:

    cheap airline tickets/EXACT
    cheap airline tickets/BROAD
    cheap airline tickets/PHRASE
    airline tickets/BROAD
    airline tickets/EXACT
    airline tickets/PHRASE

As you can see, since the results were not filtered, they weren't that great. You can improve the results by specifying additional search parameters in the selector:

    // Using the same keyword from above, filter by removing the original
    // keyword, by keeping the same match type, and by only choosing
    // "long-tail" keywords.
    new ExcludedKeywordSearchParameter(null, new Keyword[] {keyword}),
    new KeywordMatchTypeSearchParameter(null,
        new KeywordMatchType[] {keyword.getMatchType()}),
    new CompetitionSearchParameter(null,
        new CompetitionSearchParameterLevel[] {

The results are now more interesting:

    legion air tickets/BROAD
    air tram tickets/BROAD
    block air tickets/BROAD
    sheap air tickets/BROAD
    cheap airfare tracker/BROAD
    cheap airfare forum/BROAD

You will notice now that the results are beginning to give you a better idea on how you would shape your campaign. We will now explore placement functionality, formerly found within the SiteSuggestionService.

Replicating SiteSuggestionService.getSitesByUrls

In v13, you would typically retrieve a list of similar websites to expand your content network campaign using the getSitesByUrls method. Below is a snippet of code which replicates the basic functionality of this method.

    String[] urls = new String[] {"",

    LanguageTarget language = new LanguageTarget();

    CountryTarget country = new CountryTarget();

    TargetingIdeaSelector selector = new TargetingIdeaSelector();
    selector.setSearchParameters(new SearchParameter[] {
      new RelatedToUrlSearchParameter(null, urls, true),
      new PlacementTypeSearchParameter(null,
         new SiteConstantsPlacementType[] {SiteConstantsPlacementType.SITE}),
      new LanguageTargetSearchParameter(null, new LanguageTarget[] {language}),
      new CountryTargetSearchParameter(null, new CountryTarget[] {country})});
    selector.setPaging(new Paging(0, 6));

The results you get back may resemble placements like: Results,Top center,Bottom right

Though you now have a better idea of which placements you would like to pursue, you may still have difficulty ranking your results. We will finally discuss pulling additional attributes to help better evaluate targeting ideas.

Requesting more attributes

The TargetingIdeaService adds new functionality not previously found in v13 to help you better understand your results. For example, you may notice from the results above that "" looks interesting, but does not offer much information beyond its URL. To investigate, you can request that a sample URL for each placement be supplied to determine if this is the right website for you. You can do this by adding the SAMPLE_URL attribute to the requestedAttributeTypes parameter:

    // PLACEMENT is added to associate with SAMPLE_URL.
    selector.setRequestedAttributeTypes(new AttributeType[] {
      AttributeType.PLACEMENT, AttributeType.SAMPLE_URL});

When the results are returned, you will then be able to visit each sample URL to investigate the location and quality of placement yourself, something that was not previously possible with v13's SiteSuggestionService. All available attributes are listed in the AttributeType documentation page.

As we've shown in this blog post, there are many new and exciting uses for the TargetingIdeaService. We've included examples of using this service in all of our client libraries to help get you started, so please jump in and let us know of any feedback you may have on our forums.

-- Adam Rogal, AdWords API Team