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
