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");
    keyword.setMatchType(KeywordMatchType.BROAD);

    LanguageTarget language = new LanguageTarget();
    language.setLanguageCode("en");

    CountryTarget country = new CountryTarget();
    country.setCountryCode("US");

    TargetingIdeaSelector selector = new TargetingIdeaSelector();
    selector.setRequestType(RequestType.IDEAS);
    selector.setIdeaType(IdeaType.KEYWORD);
    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[] {
          CompetitionSearchParameterLevel.LOW}),

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[] {"made-up-tickets-site.com",
        "made-up-ticket-seller.com"};

    LanguageTarget language = new LanguageTarget();
    language.setLanguageCode("en");

    CountryTarget country = new CountryTarget();
    country.setCountryCode("US");

    TargetingIdeaSelector selector = new TargetingIdeaSelector();
    selector.setRequestType(RequestType.IDEAS);
    selector.setIdeaType(IdeaType.PLACEMENT);
    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:

    made-up-tickets-site.com
    made-up-tickets-site.com::Search Results,Top center
    made-up-ticket-seller.com
    made-up-ticket-seller.com::Homepage,Bottom right
    another-made-up-ticket-seller.com
    yet-another-made-up-ticket-seller.com

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 "another-made-up-ticket-seller.com" 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