Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This example demonstrates how to get keyword ideas and traffic estimates for search advertising campaigns.
Tip
Use the language selector in the documentation header to choose C#, Java, Php, or Python.
To get access and refresh tokens for your Microsoft Advertising user and make your first service call using the Bing Ads API, see the Quick Start guide. You'll want to review the Get Started guide and walkthroughs for your preferred language e.g., C#, Java, Php, and Python.
Supporting files for C#, Java, Php, and Python examples are available at GitHub. You can clone each repository or repurpose snippets as needed.
using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using Microsoft.BingAds.V13.AdInsight;
using Microsoft.BingAds;
namespace BingAdsExamplesLibrary.V13
{
/// <summary>
/// How to get keyword ideas and traffic estimates for search advertising campaigns.
/// </summary>
public class KeywordPlanner : ExampleBase
{
public override string Description
{
get { return "Keyword Planner | AdInsight V13"; }
}
public async override Task RunAsync(AuthorizationData authorizationData)
{
try
{
ApiEnvironment environment = ((OAuthDesktopMobileAuthCodeGrant)authorizationData.Authentication).Environment;
AdInsightExampleHelper AdInsightExampleHelper = new AdInsightExampleHelper(
OutputStatusMessageDefault: this.OutputStatusMessage);
AdInsightExampleHelper.AdInsightService = new ServiceClient<IAdInsightService>(
authorizationData: authorizationData,
environment: environment);
// Use the GetKeywordIdeaCategories operation to get a list of valid category identifiers.
// A category identifier will be used in the CategorySearchParameter below.
OutputStatusMessage("-----\nGetKeywordIdeaCategories:");
var getKeywordIdeaCategoriesResponse = await AdInsightExampleHelper.GetKeywordIdeaCategoriesAsync();
var categoryId = (long)(getKeywordIdeaCategoriesResponse?.KeywordIdeaCategories?.ToList()[0].CategoryId);
OutputStatusMessage(string.Format("CategoryId {0} will be used in the CategorySearchParameter below", categoryId));
// You must specify the attributes that you want in each returned KeywordIdea.
var ideaAttributes = new List<KeywordIdeaAttribute>
{
KeywordIdeaAttribute.AdGroupId,
KeywordIdeaAttribute.AdGroupName,
KeywordIdeaAttribute.AdImpressionShare,
KeywordIdeaAttribute.Competition,
KeywordIdeaAttribute.Keyword,
KeywordIdeaAttribute.MonthlySearchCounts,
KeywordIdeaAttribute.Relevance,
KeywordIdeaAttribute.Source,
KeywordIdeaAttribute.SuggestedBid,
};
var endDateTime = DateTime.UtcNow.AddMonths(-2);
// Only one of each SearchParameter type can be specified per call.
var searchParameters = new List<SearchParameter>
{
// Determines the start and end month for MonthlySearchCounts data returned with each KeywordIdea.
// The date range search parameter is optional. If you do not include the DateRangeSearchParameter
// in the GetKeywordIdeas request, then you will not be able to confirm whether the first list item
// within MonthlySearchCounts is data for the previous month, or the month prior. If the date range is
// specified and the most recent month's data is not yet available, then GetKeywordIdeas will return an error.
new DateRangeSearchParameter
{
EndDate = new DayMonthAndYear
{
Day = 30,
Month = 9,
Year = 2018
},
StartDate = new DayMonthAndYear
{
Day = 1,
Month = 9,
Year = 2018
},
},
// The CategorySearchParameter corresponds to filling in 'Your product category' under
// 'Search for new keywords using a phrase, website, or category' in the
// Microsoft Advertising web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
new CategorySearchParameter
{
// Use the GetKeywordIdeaCategories operation to get a list of valid category identifiers.
CategoryId = categoryId
},
// The QuerySearchParameter corresponds to filling in 'Product or service' under
// 'Search for new keywords using a phrase, website, or category' in the
// Microsoft Advertising web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
// When calling GetKeywordIdeas, if ExpandIdeas = false the QuerySearchParameter is required.
new QuerySearchParameter
{
Queries = new List<string>
{
"tennis",
"tennis shoes",
"running",
"running shoes",
"cross training",
"running",
},
},
// The UrlSearchParameter corresponds to filling in 'Your landing page' under
// 'Search for new keywords using a phrase, website, or category' in the
// Microsoft Advertising web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
new UrlSearchParameter
{
Url = "contoso.com"
},
// The LanguageSearchParameter, LocationSearchParameter, and NetworkSearchParameter
// correspond to the 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category' ->
// 'Targeting' workflow in the Microsoft Advertising web application.
// Each of these search parameters are required.
new LanguageSearchParameter
{
// You must specify exactly one language
Languages = new List<LanguageCriterion>
{
new LanguageCriterion
{
Language = "English",
},
},
},
new LocationSearchParameter
{
// You must include at least one location.
Locations = new List<LocationCriterion>
{
new LocationCriterion
{
// United States
LocationId = 190,
},
}
},
new NetworkSearchParameter
{
Network = new NetworkCriterion
{
Network = NetworkType.OwnedAndOperatedAndSyndicatedSearch,
}
},
// The CompetitionSearchParameter, ExcludeAccountKeywordsSearchParameter, IdeaTextSearchParameter,
// ImpressionShareSearchParameter, SearchVolumeSearchParameter, and SuggestedBidSearchParameter
// correspond to the 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category' ->
// 'Search options' workflow in the Microsoft Advertising web application.
// Use these options to refine what keywords we suggest. You can limit the keywords by historical data,
// hide keywords already in your account, and include or exclude specific keywords.
// Each of these search parameters are optional.
new CompetitionSearchParameter
{
CompetitionLevels = new List<CompetitionLevel>
{
CompetitionLevel.High,
CompetitionLevel.Medium,
CompetitionLevel.Low
}
},
new ExcludeAccountKeywordsSearchParameter
{
ExcludeAccountKeywords = false,
},
new IdeaTextSearchParameter
{
// The match type is required. Only Broad is supported.
Excluded = new List<Keyword>
{
new Keyword
{
Text = "tennis court",
MatchType = MatchType.Broad
},
new Keyword
{
Text = "tennis pro",
MatchType = MatchType.Broad
}
},
Included = new List<Keyword>
{
new Keyword
{
Text = "athletic clothing",
MatchType = MatchType.Broad
},
new Keyword
{
Text = "athletic shoes",
MatchType = MatchType.Broad
}
},
},
new ImpressionShareSearchParameter
{
// Equivalent of '0 <= value <= 50'
Maximum = 50,
Minimum = 0,
},
new SearchVolumeSearchParameter
{
// Equivalent of 'value >= 50'
Maximum = null,
Minimum = 50,
},
new SuggestedBidSearchParameter
{
// Equivalent of both 'value <= 50' and '0 <= value <= 50'
Maximum = 50,
Minimum = null,
},
// Setting the device criterion is not available in the
// 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category'
// workflow in the Microsoft Advertising web application.
// The DeviceSearchParameter is optional and by default the keyword ideas data
// are aggregated for all devices.
new DeviceSearchParameter
{
Device = new DeviceCriterion
{
// Possible values are All, Computers, Tablets, Smartphones
DeviceName = "All",
},
},
};
// If ExpandIdeas is false, the QuerySearchParameter is required.
OutputStatusMessage("-----\nGetKeywordIdeas:");
var getKeywordIdeasResponse = await AdInsightExampleHelper.GetKeywordIdeasAsync(
expandIdeas: true,
ideaAttributes: ideaAttributes,
searchParameters: searchParameters);
var keywordIdeas = getKeywordIdeasResponse?.KeywordIdeas;
if(keywordIdeas == null || keywordIdeas.Count < 1)
{
OutputStatusMessage("No keyword ideas are available for the search parameters.");
return;
}
OutputStatusMessage("KeywordIdeas:");
AdInsightExampleHelper.OutputArrayOfKeywordIdea(keywordIdeas);
// Let's get traffic estimates for each returned keyword idea.
// The returned ad group ID within each keyword idea will either be null or negative.
// Negative identifiers can be used to map the keyword ideas into suggested new ad groups.
// A null ad group identifier indicates that the keyword idea was sourced from your
// keyword idea search parameter.
// In this example we will use the suggested ad groups to request traffic estimates.
// Each of the seed keyword ideas will be submitted in the same ad group.
var adGroupIds = keywordIdeas.Select(idea => idea.AdGroupId).Distinct().ToList();
var adGroupEstimatorCount = adGroupIds.Count;
var seedOffset = adGroupIds.Contains(null) ? 0 : 1;
var adGroupEstimators = new AdGroupEstimator[adGroupEstimatorCount];
for(int index = 0; index < adGroupEstimatorCount; index++)
{
adGroupEstimators[index] = new AdGroupEstimator
{
// The AdGroupId is reserved for future use.
// The traffic estimates are not based on any specific ad group.
AdGroupId = null,
// We will add new keyword estimators while iterating the keyword ideas below.
KeywordEstimators = new List<KeywordEstimator>(),
// Optionally you can set an ad group level max CPC (maximum search bid)
MaxCpc = 5.00
};
}
foreach(var keywordIdea in keywordIdeas)
{
var keywordEstimator = new KeywordEstimator
{
Keyword = new Keyword
{
// The keyword Id is reserved for future use.
// The returned estimates are not based on any specific keyword.
Id = null,
// The match type is required. Exact, Broad, and Phrase are supported.
MatchType = MatchType.Exact,
// Use the suggested keyword
Text = keywordIdea.Keyword
},
// Round the suggested bid to two decimal places
MaxCpc = keywordIdea.SuggestedBid > 0.04 ? keywordIdea.SuggestedBid : null,
};
var index = keywordIdea.AdGroupId != null ? -(long)keywordIdea.AdGroupId - seedOffset : 0;
adGroupEstimators[index].KeywordEstimators.Add(keywordEstimator);
}
// Currently you can include only one CampaignEstimator per service call.
var campaigns = new List<CampaignEstimator>
{
new CampaignEstimator
{
// Let's use the ad group and keyword estimators that were sourced from keyword ideas above.
AdGroupEstimators = adGroupEstimators,
// The CampaignId is reserved for future use.
// The returned estimates are not based on any specific campaign.
CampaignId = null,
DailyBudget = 50.00,
NegativeKeywords = new List<NegativeKeyword>
{
new NegativeKeyword
{
Text = "foo",
MatchType = MatchType.Exact,
},
},
// The location, language, and network criterions are required for traffic estimates.
Criteria = new List<Criterion>
{
// You must include at least one location.
new LocationCriterion
{
// United States
LocationId = 190
},
// You must specify exactly one language criterion
new LanguageCriterion
{
Language = "English"
},
// You must specify exactly one network criterion
new NetworkCriterion
{
Network = NetworkType.OwnedAndOperatedAndSyndicatedSearch
},
// Optionally you can specify exactly one device.
// If you do not specify a device, the returned traffic estimates
// are aggregated for all devices.
// The "All" device name is equivalent to omitting the DeviceCriterion.
new DeviceCriterion
{
DeviceName = "All"
},
},
},
};
OutputStatusMessage("-----\nGetKeywordTrafficEstimates:");
var getKeywordTrafficEstimatesResponse = await AdInsightExampleHelper.GetKeywordTrafficEstimatesAsync(
campaignEstimators: campaigns);
OutputStatusMessage("CampaignEstimates:");
AdInsightExampleHelper.OutputArrayOfCampaignEstimate(getKeywordTrafficEstimatesResponse?.CampaignEstimates);
}
// Catch authentication exceptions
catch (OAuthTokenRequestException ex)
{
OutputStatusMessage(string.Format("Couldn't get OAuth tokens. Error: {0}. Description: {1}", ex.Details.Error, ex.Details.Description));
}
// Catch AdInsight service exceptions
catch (FaultException<AdApiFaultDetail> ex)
{
OutputStatusMessage(string.Join("; ", ex.Detail.Errors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
}
catch (FaultException<ApiFaultDetail> ex)
{
OutputStatusMessage(string.Join("; ", ex.Detail.OperationErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
OutputStatusMessage(string.Join("; ", ex.Detail.BatchErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
}
catch (Exception ex)
{
OutputStatusMessage(ex.Message);
}
}
}
}
package com.microsoft.bingads.examples.v13;
import java.util.ArrayList;
import java.util.Calendar;
import java.util.HashSet;
import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.adinsight.*;
public class KeywordPlanner extends ExampleBase {
public static void main(java.lang.String[] args) {
try
{
authorizationData = getAuthorizationData();
AdInsightExampleHelper.AdInsightService = new ServiceClient<IAdInsightService>(
authorizationData,
API_ENVIRONMENT,
IAdInsightService.class);
// Use the GetKeywordIdeaCategories operation to get a list of valid category identifiers.
// A category identifier will be used in the CategorySearchParameter below.
outputStatusMessage("-----\nGetKeywordIdeaCategories:");
GetKeywordIdeaCategoriesResponse getKeywordIdeaCategoriesResponse = AdInsightExampleHelper.getKeywordIdeaCategories();
if(getKeywordIdeaCategoriesResponse == null){
outputStatusMessage(String.format("This example requires keyword categories."));
return;
}
java.lang.Long categoryId = (long)(getKeywordIdeaCategoriesResponse.getKeywordIdeaCategories().getKeywordIdeaCategories().get(0).getCategoryId());
outputStatusMessage(String.format("CategoryId %s will be used in the CategorySearchParameter below", categoryId));
// You must specify the attributes that you want in each returned KeywordIdea.
ArrayOfKeywordIdeaAttribute ideaAttributes = new ArrayOfKeywordIdeaAttribute();
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.AD_GROUP_ID);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.AD_GROUP_NAME);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.AD_IMPRESSION_SHARE);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.COMPETITION);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.KEYWORD);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.MONTHLY_SEARCH_COUNTS);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.RELEVANCE);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.SOURCE);
ideaAttributes.getKeywordIdeaAttributes().add(KeywordIdeaAttribute.SUGGESTED_BID);
// Only one of each SearchParameter type can be specified per call.
ArrayOfSearchParameter searchParameters = new ArrayOfSearchParameter();
// Determines the start and end month for MonthlySearchCounts data returned with each KeywordIdea.
// The date range search parameter is optional. If you do not include the DateRangeSearchParameter
// in the GetKeywordIdeas request, then you will not be able to confirm whether the first list item
// within MonthlySearchCounts is data for the previous month, or the month prior. If the date range is
// specified and the most recent month's data is not yet available, then GetKeywordIdeas will return an error.
Calendar calendar = Calendar.getInstance();
DateRangeSearchParameter dateRangeSearchParameter = new DateRangeSearchParameter();
DayMonthAndYear endDate = new DayMonthAndYear();
endDate.setDay(30);
endDate.setMonth(9);
endDate.setYear(2018);
DayMonthAndYear startDate = new DayMonthAndYear();
startDate.setDay(1);
startDate.setMonth(9);
startDate.setYear(2018);
dateRangeSearchParameter.setEndDate(endDate);
dateRangeSearchParameter.setStartDate(startDate);
searchParameters.getSearchParameters().add(dateRangeSearchParameter);
// The CategorySearchParameter corresponds to filling in 'Your product category' under
// 'Search for new keywords using a phrase, website, or category' in the
// Bing Ads web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
CategorySearchParameter categorySearchParameter = new CategorySearchParameter();
// Use the GetKeywordIdeaCategories operation (e.g., above) to get a list of valid category identifiers.
categorySearchParameter.setCategoryId(categoryId);
searchParameters.getSearchParameters().add(categorySearchParameter);
// The QuerySearchParameter corresponds to filling in 'Product or service' under
// 'Search for new keywords using a phrase, website, or category' in the
// Bing Ads web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
// When calling GetKeywordIdeas, if ExpandIdeas = false the QuerySearchParameter is required.
QuerySearchParameter querySearchParameter = new QuerySearchParameter();
ArrayOfstring queries = new ArrayOfstring();
queries.getStrings().add("tennis");
queries.getStrings().add("tennis shoes");
queries.getStrings().add("running");
queries.getStrings().add("running shoes");
queries.getStrings().add("cross training");
querySearchParameter.setQueries(queries);
searchParameters.getSearchParameters().add(querySearchParameter);
// The UrlSearchParameter corresponds to filling in 'Your landing page' under
// 'Search for new keywords using a phrase, website, or category' in the
// Bing Ads web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
UrlSearchParameter urlSearchParameter = new UrlSearchParameter();
urlSearchParameter.setUrl("contoso.com");
searchParameters.getSearchParameters().add(urlSearchParameter);
// The LanguageSearchParameter, LocationSearchParameter, and NetworkSearchParameter
// correspond to the 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category' ->
// 'Targeting' workflow in the Bing Ads web application.
// Each of these search parameters are required.
LanguageSearchParameter languageSearchParameter = new LanguageSearchParameter();
ArrayOfLanguageCriterion languages = new ArrayOfLanguageCriterion();
LanguageCriterion englishLanguage = new LanguageCriterion();
englishLanguage.setLanguage("English");
// You must specify exactly one language
languages.getLanguageCriterions().add(englishLanguage);
languageSearchParameter.setLanguages(languages);
searchParameters.getSearchParameters().add(languageSearchParameter);
LocationSearchParameter locationSearchParameter = new LocationSearchParameter();
ArrayOfLocationCriterion locations = new ArrayOfLocationCriterion();
LocationCriterion unitedStatesLocationCriterion = new LocationCriterion();
// United States
unitedStatesLocationCriterion.setLocationId(190L);
// You must specify between 1 and 100 locations
locations.getLocationCriterions().add(unitedStatesLocationCriterion);
locationSearchParameter.setLocations(locations);
searchParameters.getSearchParameters().add(locationSearchParameter);
NetworkSearchParameter networkSearchParameter = new NetworkSearchParameter();
NetworkCriterion networkCriterion = new NetworkCriterion();
networkCriterion.setNetwork(NetworkType.OWNED_AND_OPERATED_AND_SYNDICATED_SEARCH);
networkSearchParameter.setNetwork(networkCriterion);
searchParameters.getSearchParameters().add(networkSearchParameter);
// The CompetitionSearchParameter, ExcludeAccountKeywordsSearchParameter, IdeaTextSearchParameter,
// ImpressionShareSearchParameter, SearchVolumeSearchParameter, and SuggestedBidSearchParameter
// correspond to the 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category' ->
// 'Search options' workflow in the Bing Ads web application.
// Use these options to refine what keywords we suggest. You can limit the keywords by historical data,
// hide keywords already in your account, and include or exclude specific keywords.
// Each of these search parameters are optional.
CompetitionSearchParameter competitionSearchParameter = new CompetitionSearchParameter();
ArrayOfCompetitionLevel competitionLevels = new ArrayOfCompetitionLevel();
competitionLevels.getCompetitionLevels().add(CompetitionLevel.LOW);
competitionLevels.getCompetitionLevels().add(CompetitionLevel.MEDIUM);
competitionLevels.getCompetitionLevels().add(CompetitionLevel.HIGH);
competitionSearchParameter.setCompetitionLevels(competitionLevels);
searchParameters.getSearchParameters().add(competitionSearchParameter);
ExcludeAccountKeywordsSearchParameter excludeAccountKeywordsSearchParameter = new ExcludeAccountKeywordsSearchParameter();
excludeAccountKeywordsSearchParameter.setExcludeAccountKeywords(false);
searchParameters.getSearchParameters().add(excludeAccountKeywordsSearchParameter);
IdeaTextSearchParameter ideaTextSearchParameter = new IdeaTextSearchParameter();
// The match type is required. Only Broad is supported.
ArrayOfKeyword excludedKeywords = new ArrayOfKeyword();
Keyword excludedKeyword1 = new Keyword();
excludedKeyword1.setText("tennis court");
excludedKeyword1.setMatchType(MatchType.BROAD);
excludedKeywords.getKeywords().add(excludedKeyword1);
Keyword excludedKeyword2 = new Keyword();
excludedKeyword2.setText("tennis pro");
excludedKeyword2.setMatchType(MatchType.BROAD);
excludedKeywords.getKeywords().add(excludedKeyword2);
ArrayOfKeyword includedKeywords = new ArrayOfKeyword();
Keyword includedKeyword1 = new Keyword();
includedKeyword1.setText("athletic clothing");
includedKeyword1.setMatchType(MatchType.BROAD);
includedKeywords.getKeywords().add(includedKeyword1);
Keyword includedKeyword2 = new Keyword();
includedKeyword2.setText("athletic shoes");
includedKeyword2.setMatchType(MatchType.BROAD);
includedKeywords.getKeywords().add(includedKeyword2);
ideaTextSearchParameter.setExcluded(excludedKeywords);
ideaTextSearchParameter.setIncluded(includedKeywords);
searchParameters.getSearchParameters().add(ideaTextSearchParameter);
// Equivalent of '0 <= value <= 50'
ImpressionShareSearchParameter impressionShareSearchParameter = new ImpressionShareSearchParameter();
impressionShareSearchParameter.setMaximum(50D);
impressionShareSearchParameter.setMinimum(0D);
searchParameters.getSearchParameters().add(impressionShareSearchParameter);
// Equivalent of 'value >= 50'
SearchVolumeSearchParameter searchVolumeSearchParameter = new SearchVolumeSearchParameter();
searchVolumeSearchParameter.setMaximum(null);
searchVolumeSearchParameter.setMinimum(50L);
searchParameters.getSearchParameters().add(searchVolumeSearchParameter);
// Equivalent of both 'value <= 50' and '0 <= value <= 50'
SuggestedBidSearchParameter suggestedBidSearchParameter = new SuggestedBidSearchParameter();
suggestedBidSearchParameter.setMaximum(50D);
suggestedBidSearchParameter.setMinimum(null);
searchParameters.getSearchParameters().add(suggestedBidSearchParameter);
// Setting the device criterion is not available in the
// 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category'
// workflow in the Bing Ads web application.
// The DeviceSearchParameter is optional and by default the keyword ideas data
// are aggregated for all devices.
DeviceSearchParameter deviceSearchParameter = new DeviceSearchParameter();
DeviceCriterion deviceCriterion = new DeviceCriterion();
// Possible values are All, Computers, Tablets, Smartphones
deviceCriterion.setDeviceName("All");
deviceSearchParameter.setDevice(deviceCriterion);
searchParameters.getSearchParameters().add(deviceSearchParameter);
// If ExpandIdeas is false, the QuerySearchParameter is required.
outputStatusMessage("-----\nGetKeywordIdeas:");
GetKeywordIdeasResponse getKeywordIdeasResponse = AdInsightExampleHelper.getKeywordIdeas(
true,
ideaAttributes,
searchParameters);
ArrayOfKeywordIdea keywordIdeas = getKeywordIdeasResponse.getKeywordIdeas();
if(keywordIdeas == null || keywordIdeas.getKeywordIdeas().size() < 1)
{
outputStatusMessage("No keyword ideas are available for the search parameters.");
return;
}
outputStatusMessage("KeywordIdeas:");
AdInsightExampleHelper.outputArrayOfKeywordIdea(keywordIdeas);
// Let's get traffic estimates for each returned keyword idea.
// The returned ad group ID within each keyword idea will either be null or negative.
// Negative identifiers can be used to map the keyword ideas into suggested new ad groups.
// A null ad group identifier indicates that the keyword idea was sourced from your
// keyword idea search parameter.
// In this example we will use the suggested ad groups to request traffic estimates.
// Each of the seed keyword ideas will be submitted in the same ad group.
ArrayOflong keywordIdeaAdGroupIds = new ArrayOflong();
for(KeywordIdea keywordIdea : keywordIdeas.getKeywordIdeas()){
keywordIdeaAdGroupIds.getLongs().add(keywordIdea.getAdGroupId());
}
ArrayList<java.lang.Long> adGroupIds = new ArrayList<java.lang.Long>(new HashSet<Long>(keywordIdeaAdGroupIds.getLongs()));
int adGroupEstimatorCount = adGroupIds.size();
int seedOffset = adGroupIds.contains(null) ? 0 : 1;
AdGroupEstimator[] adGroupEstimators = new AdGroupEstimator[adGroupEstimatorCount];
for(int index = 0; index < adGroupEstimatorCount; index++)
{
adGroupEstimators[index] = new AdGroupEstimator();
// The AdGroupId is reserved for future use.
// The traffic estimates are not based on any specific ad group.
adGroupEstimators[index].setAdGroupId(null);
// Optionally you can set an ad group level max CPC (maximum search bid)
adGroupEstimators[index].setMaxCpc(5.00D);
// We will add new keyword estimators while iterating the keyword ideas below.
ArrayOfKeywordEstimator keywordEstimators = new ArrayOfKeywordEstimator();
adGroupEstimators[index].setKeywordEstimators(keywordEstimators);
}
for(KeywordIdea keywordIdea : keywordIdeas.getKeywordIdeas())
{
KeywordEstimator keywordEstimator = new KeywordEstimator();
Keyword keyword = new Keyword();
// The keyword Id is reserved for future use.
// The returned estimates are not based on any specific keyword.
keyword.setId(null);
// The match type is required. Exact, Broad, and Phrase are supported.
keyword.setMatchType(MatchType.EXACT);
// Use the suggested keyword
keyword.setText(keywordIdea.getKeyword());
keywordEstimator.setKeyword(keyword);
double maxCpc = keywordIdea.getSuggestedBid() > 0.04 ?
keywordIdea.getSuggestedBid() : null;
keywordEstimator.setMaxCpc(maxCpc);
long index = keywordIdea.getAdGroupId() != null ? -(long)keywordIdea.getAdGroupId() - seedOffset : 0;
adGroupEstimators[(int)index].getKeywordEstimators().getKeywordEstimators().add(keywordEstimator);
}
// Currently you can include only one CampaignEstimator per service call.
ArrayOfCampaignEstimator campaigns = new ArrayOfCampaignEstimator();
CampaignEstimator campaignEstimator = new CampaignEstimator();
// Let's use the ad group and keyword estimators that were sourced from keyword ideas above.
ArrayOfAdGroupEstimator adGroups = new ArrayOfAdGroupEstimator();
for(int index = 0; index < adGroupEstimatorCount; index++)
{
adGroups.getAdGroupEstimators().add(adGroupEstimators[index]);
}
campaignEstimator.setAdGroupEstimators(adGroups);
// The CampaignId is reserved for future use.
// The returned estimates are not based on any specific campaign.
campaignEstimator.setCampaignId(null);
campaignEstimator.setDailyBudget(50.00D);
ArrayOfNegativeKeyword negativeKeywords = new ArrayOfNegativeKeyword();
NegativeKeyword negativeKeyword = new NegativeKeyword();
negativeKeyword.setText("foo");
negativeKeyword.setMatchType(MatchType.EXACT);
negativeKeywords.getNegativeKeywords().add(negativeKeyword);
campaignEstimator.setNegativeKeywords(negativeKeywords);
// The location, language, and network criterions are required for traffic estimates.
ArrayOfCriterion trafficEstimateCriteria = new ArrayOfCriterion();
// You must specify between 1 and 100 locations
trafficEstimateCriteria.getCriterions().add(unitedStatesLocationCriterion);
// You must specify exactly one language criterion
trafficEstimateCriteria.getCriterions().add(englishLanguage);
// You must specify exactly one network criterion
trafficEstimateCriteria.getCriterions().add(networkCriterion);
// Optionally you can specify exactly one device.
// If you do not specify a device, the returned traffic estimates
// are aggregated for all devices.
// The "All" device name is equivalent to omitting the DeviceCriterion.
trafficEstimateCriteria.getCriterions().add(deviceCriterion);
campaignEstimator.setCriteria(trafficEstimateCriteria);
campaigns.getCampaignEstimators().add(campaignEstimator);
outputStatusMessage("-----\nGetKeywordTrafficEstimates:");
GetKeywordTrafficEstimatesResponse getKeywordTrafficEstimatesResponse = AdInsightExampleHelper.getKeywordTrafficEstimates(
campaigns);
outputStatusMessage("CampaignEstimates:");
AdInsightExampleHelper.outputArrayOfCampaignEstimate(getKeywordTrafficEstimatesResponse.getCampaignEstimates());
}
catch (Exception ex) {
String faultXml = ExampleExceptionHelper.getBingAdsExceptionFaultXml(ex, System.out);
outputStatusMessage(faultXml);
String message = ExampleExceptionHelper.handleBingAdsSDKException(ex, System.out);
outputStatusMessage(message);
}
}
}
<?php
namespace Microsoft\BingAds\Samples\V13;
// For more information about installing and using the Bing Ads PHP SDK,
// see https://go.microsoft.com/fwlink/?linkid=838593.
require_once __DIR__ . "/../vendor/autoload.php";
include __DIR__ . "/AuthHelper.php";
include __DIR__ . "/AdInsightExampleHelper.php";
include __DIR__ . "/CampaignManagementExampleHelper.php";
use SoapVar;
use SoapFault;
use Exception;
use DateTime;
// Specify the Microsoft\BingAds\Auth classes that will be used.
use Microsoft\BingAds\Auth\ServiceClient;
use Microsoft\BingAds\Auth\ServiceClientType;
// Specify the Microsoft\BingAds\Samples classes that will be used.
use Microsoft\BingAds\Samples\V13\AuthHelper;
use Microsoft\BingAds\Samples\V13\AdInsightExampleHelper;
// Specify the Microsoft\BingAds\V13\AdInsight classes that will be used.
use Microsoft\BingAds\V13\AdInsight\KeywordIdeaAttribute;
use Microsoft\BingAds\V13\AdInsight\SearchParameter;
use Microsoft\BingAds\V13\AdInsight\DateRangeSearchParameter;
use Microsoft\BingAds\V13\AdInsight\DayMonthAndYear;
use Microsoft\BingAds\V13\AdInsight\CategorySearchParameter;
use Microsoft\BingAds\V13\AdInsight\QuerySearchParameter;
use Microsoft\BingAds\V13\AdInsight\UrlSearchParameter;
use Microsoft\BingAds\V13\AdInsight\LanguageSearchParameter;
use Microsoft\BingAds\V13\AdInsight\Criterion;
use Microsoft\BingAds\V13\AdInsight\LanguageCriterion;
use Microsoft\BingAds\V13\AdInsight\LocationSearchParameter;
use Microsoft\BingAds\V13\AdInsight\LocationCriterion;
use Microsoft\BingAds\V13\AdInsight\NetworkSearchParameter;
use Microsoft\BingAds\V13\AdInsight\NetworkCriterion;
use Microsoft\BingAds\V13\AdInsight\NetworkType;
use Microsoft\BingAds\V13\AdInsight\CompetitionSearchParameter;
use Microsoft\BingAds\V13\AdInsight\CompetitionLevel;
use Microsoft\BingAds\V13\AdInsight\ExcludeAccountKeywordsSearchParameter;
use Microsoft\BingAds\V13\AdInsight\IdeaTextSearchParameter;
use Microsoft\BingAds\V13\AdInsight\Keyword;
use Microsoft\BingAds\V13\AdInsight\MatchType;
use Microsoft\BingAds\V13\AdInsight\ImpressionShareSearchParameter;
use Microsoft\BingAds\V13\AdInsight\SearchVolumeSearchParameter;
use Microsoft\BingAds\V13\AdInsight\SuggestedBidSearchParameter;
use Microsoft\BingAds\V13\AdInsight\DeviceSearchParameter;
use Microsoft\BingAds\V13\AdInsight\DeviceCriterion;
use Microsoft\BingAds\V13\AdInsight\AdGroupEstimator;
use Microsoft\BingAds\V13\AdInsight\KeywordEstimator;
use Microsoft\BingAds\V13\AdInsight\CampaignEstimator;
use Microsoft\BingAds\V13\AdInsight\AdGroupEstimate;
use Microsoft\BingAds\V13\AdInsight\KeywordEstimate;
use Microsoft\BingAds\V13\AdInsight\CampaignEstimate;
use Microsoft\BingAds\V13\AdInsight\NegativeKeyword;
try
{
// Authenticate user credentials and set the account ID for the sample.
AuthHelper::Authenticate();
print("-----\r\nGetKeywordIdeaCategories:\r\n");
$getKeywordIdeaCategoriesResponse = AdInsightExampleHelper::GetKeywordIdeaCategories();
$categoryId = $getKeywordIdeaCategoriesResponse->KeywordIdeaCategories->KeywordIdeaCategory[0]->CategoryId;
printf("CategoryId %s will be used in the CategorySearchParameter below\r\n", $categoryId);
// You must specify the attributes that you want in each returned KeywordIdea.
$ideaAttributes = array();
$ideaAttributes[] = KeywordIdeaAttribute::AdGroupId;
$ideaAttributes[] = KeywordIdeaAttribute::AdGroupName;
$ideaAttributes[] = KeywordIdeaAttribute::AdImpressionShare;
$ideaAttributes[] = KeywordIdeaAttribute::Competition;
$ideaAttributes[] = KeywordIdeaAttribute::Keyword;
$ideaAttributes[] = KeywordIdeaAttribute::MonthlySearchCounts;
$ideaAttributes[] = KeywordIdeaAttribute::Relevance;
$ideaAttributes[] = KeywordIdeaAttribute::Source;
$ideaAttributes[] = KeywordIdeaAttribute::SuggestedBid;
date_default_timezone_set('UTC');
$now = new DateTime(gmdate('Y-m-d H:i:s', time()));
// Only one of each SearchParameter type can be specified per call.
$searchParameters = array();
// Determines the start and end month for MonthlySearchCounts data returned with each KeywordIdea.
// The date range search parameter is optional. If you do not include the DateRangeSearchParameter
// in the GetKeywordIdeas request, then you will not be able to confirm whether the first list item
// within MonthlySearchCounts is data for the previous month, or the month prior. If the date range is
// specified and the most recent month's data is not yet available, then GetKeywordIdeas will return an error.
$dateRangeSearchParameter = new DateRangeSearchParameter();
$dateRangeSearchParameterEndDate = new DayMonthAndYear();
$dateRangeSearchParameterEndDate->Day = 30;
$dateRangeSearchParameterEndDate->Month = 9;
$dateRangeSearchParameterEndDate->Year = 2018;
$dateRangeSearchParameter->EndDate = $dateRangeSearchParameterEndDate;
$dateRangeSearchParameterStartDate = new DayMonthAndYear();
$dateRangeSearchParameterStartDate->Day = 1;
$dateRangeSearchParameterStartDate->Month = 9;
$dateRangeSearchParameterStartDate->Year = 2018;
$dateRangeSearchParameter->StartDate = $dateRangeSearchParameterStartDate;
$searchParameters[] = new SoapVar(
$dateRangeSearchParameter,
SOAP_ENC_OBJECT,
'DateRangeSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// The CategorySearchParameter corresponds to filling in 'Your product category' under
// 'Search for new keywords using a phrase, website, or category' in the
// Bing Ads web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
$categorySearchParameter = new CategorySearchParameter();
$categorySearchParameter->CategoryId = $categoryId;
$searchParameters[] = new SoapVar(
$categorySearchParameter,
SOAP_ENC_OBJECT,
'CategorySearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// The QuerySearchParameter corresponds to filling in 'Product or service' under
// 'Search for new keywords using a phrase, website, or category' in the
// Bing Ads web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
// When calling GetKeywordIdeas, if ExpandIdeas = false the QuerySearchParameter is required.
$querySearchParameter = new QuerySearchParameter();
$querySearchParameter->Queries = array("tennis", "tennis shoes", "running", "running shoes", "cross training", "running");
$searchParameters[] = new SoapVar(
$querySearchParameter,
SOAP_ENC_OBJECT,
'QuerySearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// The UrlSearchParameter corresponds to filling in 'Your landing page' under
// 'Search for new keywords using a phrase, website, or category' in the
// Bing Ads web application's Keyword Planner tool.
// One or more CategorySearchParameter, QuerySearchParameter, or UrlSearchParameter is required.
$urlSearchParameter = new UrlSearchParameter();
$urlSearchParameter->Url = "contoso.com";
$searchParameters[] = new SoapVar(
$urlSearchParameter,
SOAP_ENC_OBJECT,
'UrlSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// The LanguageSearchParameter, LocationSearchParameter, and NetworkSearchParameter
// correspond to the 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category' ->
// 'Targeting' workflow in the Bing Ads web application.
// Each of these search parameters are required.
$languageSearchParameter = new LanguageSearchParameter();
$languageCriterion = new LanguageCriterion();
$languageCriterion->Language = "English";
// You must specify exactly one language
$languageSearchParameter->Languages[] = new SoapVar(
$languageCriterion,
SOAP_ENC_OBJECT,
'LanguageCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$searchParameters[] = new SoapVar(
$languageSearchParameter,
SOAP_ENC_OBJECT,
'LanguageSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$locationSearchParameter = new LocationSearchParameter();
$locationSearchParameter->Locations = array();
$locationCriterion = new LocationCriterion();
// United States
$locationCriterion->LocationId = 190;
// You must specify between 1 and 100 locations
$locationSearchParameter->Locations[] = new SoapVar(
$locationCriterion,
SOAP_ENC_OBJECT,
'LocationCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$searchParameters[] = new SoapVar(
$locationSearchParameter,
SOAP_ENC_OBJECT,
'LocationSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$networkSearchParameter = new NetworkSearchParameter();
$networkCriterion = new NetworkCriterion();
$networkCriterion->Network = NetworkType::OwnedAndOperatedAndSyndicatedSearch;
$networkSearchParameter->Network = new SoapVar(
$networkCriterion,
SOAP_ENC_OBJECT,
'NetworkCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$searchParameters[] = new SoapVar(
$networkSearchParameter,
SOAP_ENC_OBJECT,
'NetworkSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// The CompetitionSearchParameter, ExcludeAccountKeywordsSearchParameter, IdeaTextSearchParameter,
// ImpressionShareSearchParameter, SearchVolumeSearchParameter, and SuggestedBidSearchParameter
// correspond to the 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category' ->
// 'Search options' workflow in the Bing Ads web application.
// Use these options to refine what keywords we suggest. You can limit the keywords by historical data,
// hide keywords already in your account, and include or exclude specific keywords.
// Each of these search parameters are optional.
$competitionSearchParameter = new CompetitionSearchParameter();
$competitionLevels = array(CompetitionLevel::High, CompetitionLevel::Medium, CompetitionLevel::Low);
$competitionSearchParameter->CompetitionLevels = $competitionLevels;
$searchParameters[] = new SoapVar(
$competitionSearchParameter,
SOAP_ENC_OBJECT,
'CompetitionSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$excludeAccountKeywordsSearchParameter = new ExcludeAccountKeywordsSearchParameter();
$excludeAccountKeywordsSearchParameter->ExcludeAccountKeywords = false;
$searchParameters[] = new SoapVar(
$excludeAccountKeywordsSearchParameter,
SOAP_ENC_OBJECT,
'ExcludeAccountKeywordsSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$ideaTextSearchParameter = new IdeaTextSearchParameter();
$excludedKeywords = array();
$excludedKeyword1 = new Keyword();
$excludedKeyword1->Text = "tennis court";
// The match type is required. Only Broad is supported.
$excludedKeyword1->MatchType = MatchType::Broad;
$excludedKeywords[] = $excludedKeyword1;
$excludedKeyword2 = new Keyword();
$excludedKeyword2->Text = "tennis pro";
$excludedKeyword2->MatchType = MatchType::Broad;
$excludedKeywords[] = $excludedKeyword2;
$ideaTextSearchParameter->Excluded = $excludedKeywords;
$includedKeyword1 = new Keyword();
$includedKeyword1->Text = "athletic clothing";
$includedKeyword1->MatchType = MatchType::Broad;
$includedKeywords[] = $includedKeyword1;
$includedKeyword2 = new Keyword();
$includedKeyword2->Text = "athletic shoes";
$includedKeyword2->MatchType = MatchType::Broad;
$includedKeywords[] = $includedKeyword2;
$ideaTextSearchParameter->Included = $includedKeywords;
$searchParameters[] = new SoapVar(
$ideaTextSearchParameter,
SOAP_ENC_OBJECT,
'IdeaTextSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$impressionShareSearchParameter = new ImpressionShareSearchParameter();
// Equivalent of '0 <= value <= 50'
$impressionShareSearchParameter->Maximum = 50;
$impressionShareSearchParameter->Minimum = 0;
$searchParameters[] = new SoapVar(
$impressionShareSearchParameter,
SOAP_ENC_OBJECT,
'ImpressionShareSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$searchVolumeSearchParameter = new SearchVolumeSearchParameter();
// Equivalent of 'value >= 50'
$searchVolumeSearchParameter->Maximum = null;
$searchVolumeSearchParameter->Minimum = 50;
$searchParameters[] = new SoapVar(
$searchVolumeSearchParameter,
SOAP_ENC_OBJECT,
'SearchVolumeSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$suggestedBidSearchParameter = new SuggestedBidSearchParameter();
// Equivalent of both 'value <= 50' and '0 <= value <= 50'
$suggestedBidSearchParameter->Maximum = 50;
$suggestedBidSearchParameter->Minimum = null;
$searchParameters[] = new SoapVar(
$suggestedBidSearchParameter,
SOAP_ENC_OBJECT,
'SuggestedBidSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// Setting the device criterion is not available in the
// 'Keyword Planner' -> 'Search for new keywords using a phrase, website, or category'
// workflow in the Bing Ads web application.
// The DeviceSearchParameter is optional and by default the keyword ideas data
// are aggregated for all devices.
$deviceSearchParameter = new DeviceSearchParameter();
$deviceCriterion = new DeviceCriterion();
// Possible values are All, Computers, Tablets, Smartphones
$deviceCriterion->DeviceName = "All";
$deviceSearchParameter->Device = new SoapVar(
$deviceCriterion, SOAP_ENC_OBJECT,
'DeviceCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace());
$searchParameters[] = new SoapVar(
$deviceSearchParameter,
SOAP_ENC_OBJECT,
'DeviceSearchParameter',
$GLOBALS['AdInsightProxy']->GetNamespace());
// If ExpandIdeas is false, the QuerySearchParameter is required.
$expandIdeas = true;
print("-----\r\nGetKeywordIdeas:\r\n");
$getKeywordIdeasResponse = AdInsightExampleHelper::GetKeywordIdeas(
$expandIdeas,
$ideaAttributes,
$searchParameters
);
$keywordIdeas = $getKeywordIdeasResponse->KeywordIdeas;
if(!isset($getKeywordIdeasResponse->KeywordIdeas) || count($keywordIdeas) < 1)
{
printf("No keyword ideas are available for the search parameters.\r\n");
return;
}
print("KeywordIdeas:\r\n");
AdInsightExampleHelper::OutputArrayOfKeywordIdea($keywordIdeas);
// Let's get traffic estimates for each returned keyword idea.
// The returned ad group ID within each keyword idea will either be null or negative.
// Negative identifiers can be used to map the keyword ideas into suggested new ad groups.
// A null ad group identifier indicates that the keyword idea was sourced from your
// keyword idea search parameter.
// In this example we will use the suggested ad groups to request traffic estimates.
// Each of the seed keyword ideas will be submitted in the same ad group estimator.
$ideaAdGroupIds = array();
foreach ($keywordIdeas->KeywordIdea as $keywordIdea)
{
$ideaAdGroupIds[] = $keywordIdea->AdGroupId;
}
$adGroupIds = array_unique($ideaAdGroupIds, SORT_REGULAR);
$adGroupEstimatorCount = count($adGroupIds);
// If any ad group IDs are null, traffic estimates for all of those keyword ideas
// will be submitted via $adGroupEstimators[0]. If none of the ad group IDs are null,
// then $adGroupEstimators[0] will correspond to keyword ideas where AdGroupId is -1.
// Each KeywordIdea is assigned to an AdGroupEstimator below.
$seedOffset = in_array(null, $adGroupIds) ? 0 : 1;
$adGroupEstimators = array();
for($index = 0; $index < $adGroupEstimatorCount; $index++)
{
$adGroupEstimator = new AdGroupEstimator();
// The AdGroupId is reserved for future use.
// The traffic estimates are not based on any specific ad group.
$adGroupEstimator->AdGroupId = null;
// We will add new keyword estimators while iterating the keyword ideas below.
$adGroupEstimator->KeywordEstimators = array();
// Optionally you can set an ad group level max CPC (maximum search bid)
$adGroupEstimator->MaxCpc = 5.00;
$adGroupEstimators[] = $adGroupEstimator;
}
foreach($keywordIdeas->KeywordIdea as $keywordIdea)
{
$keywordEstimator = new KeywordEstimator();
$keyword = new Keyword();
// The keyword Id is reserved for future use.
// The returned estimates are not based on any specific keyword.
$keyword->Id = null;
// The match type is required. Exact, Broad, and Phrase are supported.
$keyword->MatchType = MatchType::Exact;
// Use the suggested keyword
$keyword->Text = $keywordIdea->Keyword;
$keywordEstimator->Keyword = $keyword;
$keywordEstimator->MaxCpc = $keywordIdea->SuggestedBid > 0.04 ? $keywordIdea->SuggestedBid : null;
$index = ($keywordIdea->AdGroupId != null) ? -($keywordIdea->AdGroupId) - $seedOffset : 0;
$adGroupEstimators[$index]->KeywordEstimators[] = $keywordEstimator;
}
// Currently you can include only one CampaignEstimator per service call.
$campaignEstimators = array();
$campaignEstimator = new CampaignEstimator();
// Let's use the ad group and keyword estimators that were sourced from keyword ideas above.
$campaignEstimator->AdGroupEstimators = $adGroupEstimators;
// The CampaignId is reserved for future use.
// The returned estimates are not based on any specific campaign.
$campaignEstimator->CampaignId = null;
$campaignEstimator->DailyBudget = 50.00;
$campaignEstimator->NegativeKeywords = array();
$negativeKeyword = new NegativeKeyword();
$negativeKeyword->Text = "foo";
$negativeKeyword->MatchType = MatchType::Exact;
$campaignEstimator->NegativeKeywords[] = $negativeKeyword;
// The location, language, and network criterions are required for traffic estimates.
$campaignEstimator->Criteria = array();
// You must specify between 1 and 100 locations
$locationSearchParameter->Locations = array();
$locationCriterion = new LocationCriterion();
// United States
$locationCriterion->LocationId = 190;
$campaignEstimator->Criteria[] = new SoapVar(
$locationCriterion,
SOAP_ENC_OBJECT,
'LocationCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// You must specify exactly one language criterion
$languageCriterion = new LanguageCriterion();
$languageCriterion->Language = "English";
$campaignEstimator->Criteria[] = new SoapVar(
$languageCriterion,
SOAP_ENC_OBJECT,
'LanguageCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace());
// You must specify exactly one network criterion
$networkSearchParameter = new NetworkSearchParameter();
$networkCriterion = new NetworkCriterion();
$networkCriterion->Network = NetworkType::OwnedAndOperatedAndSyndicatedSearch;
$campaignEstimator->Criteria[] = new SoapVar(
$networkCriterion,
SOAP_ENC_OBJECT,
'NetworkCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
// Optionally you can specify exactly one device.
// If you do not specify a device, the returned traffic estimates
// are aggregated for all devices.
// The "All" device name is equivalent to omitting the DeviceCriterion.
$deviceCriterion = new DeviceCriterion();
$deviceCriterion->DeviceName = "All";
$campaignEstimator->Criteria[] = new SoapVar(
$deviceCriterion,
SOAP_ENC_OBJECT,
'DeviceCriterion',
$GLOBALS['AdInsightProxy']->GetNamespace()
);
$campaignEstimators[] = $campaignEstimator;
print("-----\r\nGetKeywordTrafficEstimates:\r\n");
$getKeywordTrafficEstimatesResponse = AdInsightExampleHelper::GetKeywordTrafficEstimates(
$campaignEstimators
);
print("CampaignEstimates:\r\n");
AdInsightExampleHelper::OutputArrayOfCampaignEstimate($getKeywordTrafficEstimatesResponse->CampaignEstimates);
}
catch (SoapFault $e)
{
printf("-----\r\nFault Code: %s\r\nFault String: %s\r\nFault Detail: \r\n", $e->faultcode, $e->faultstring);
var_dump($e->detail);
print "-----\r\nLast SOAP request/response:\r\n";
print $GLOBALS['Proxy']->GetWsdl() . "\r\n";
print $GLOBALS['Proxy']->GetService()->__getLastRequest()."\r\n";
print $GLOBALS['Proxy']->GetService()->__getLastResponse()."\r\n";
}
catch (Exception $e)
{
// Ignore fault exceptions that we already caught.
if ($e->getPrevious())
{ ; }
else
{
print $e->getCode()." ".$e->getMessage()."\n\n";
print $e->getTraceAsString()."\n\n";
}
}
from datetime import datetime
from auth_helper import *
from openapi_client.models.adinsight import *
def main():
try:
# Test 1: Get Keyword Ideas
print("=" * 60)
print("Test 1: Getting Keyword Ideas...")
print("=" * 60)
# Define attributes we want to retrieve for each keyword idea
idea_attributes = [
KeywordIdeaAttribute.ADGROUPID,
KeywordIdeaAttribute.ADGROUPNAME,
KeywordIdeaAttribute.KEYWORD,
KeywordIdeaAttribute.SOURCE,
KeywordIdeaAttribute.MONTHLYSEARCHCOUNTS,
KeywordIdeaAttribute.SUGGESTEDBID,
KeywordIdeaAttribute.COMPETITION,
KeywordIdeaAttribute.RELEVANCE,
KeywordIdeaAttribute.ADIMPRESSIONSHARE
]
# Set up search parameters
search_parameters = []
# Date range parameter
current_date = datetime.now()
start_date = DayMonthAndYear(
day=1,
month=1,
year=current_date.year - 1
)
end_date = DayMonthAndYear(
day=1,
month=current_date.month - 1 if current_date.month > 1 else 12,
year=current_date.year - 1
)
date_range_param = DateRangeSearchParameter(
start_date=start_date,
end_date=end_date
)
search_parameters.append(date_range_param)
# Query search parameter
query_param = QuerySearchParameter(
queries=["tennis", "tennis shoes", "running", "running shoes", "cross training", "running"]
)
search_parameters.append(query_param)
# Language parameter
language_criterion = LanguageCriterion(
language="English"
)
language_param = LanguageSearchParameter(
languages=[language_criterion]
)
search_parameters.append(language_param)
# Location parameter (United States)
location_criterion = LocationCriterion(
location_id='190'
)
location_param = LocationSearchParameter(
locations=[location_criterion]
)
search_parameters.append(location_param)
# Network parameter
network_criterion = NetworkCriterion(
network=NetworkType.OWNEDANDOPERATEDANDSYNDICATEDSEARCH
)
network_param = NetworkSearchParameter(
network=network_criterion
)
search_parameters.append(network_param)
# Create the request
get_keyword_ideas_request = GetKeywordIdeasRequest(
expand_ideas=True,
idea_attributes=idea_attributes,
search_parameters=search_parameters
)
# Call the service
keyword_ideas_response = ad_insight_service.get_keyword_ideas(
get_keyword_ideas_request=get_keyword_ideas_request
)
keyword_ideas = keyword_ideas_response.KeywordIdeas
if not keyword_ideas or len(keyword_ideas) == 0:
print("No keyword ideas found.")
return
print(f"\nFound {len(keyword_ideas)} keyword ideas:")
# Display first few keyword ideas
for i, idea in enumerate(keyword_ideas[:10]): # Show first 10
print(f"\n Keyword Idea {i+1}:")
if hasattr(idea, 'Keyword'):
print(f" Keyword: {idea.Keyword}")
if hasattr(idea, 'Source'):
print(f" Source: {idea.Source}")
if hasattr(idea, 'AdGroupId'):
print(f" AdGroupId: {idea.AdGroupId}")
if hasattr(idea, 'AdGroupName'):
print(f" AdGroupName: {idea.AdGroupName}")
if hasattr(idea, 'SuggestedBid'):
print(f" SuggestedBid: {idea.SuggestedBid}")
if hasattr(idea, 'Competition'):
print(f" Competition: {idea.Competition}")
if hasattr(idea, 'Relevance'):
print(f" Relevance: {idea.Relevance}")
if hasattr(idea, 'MonthlySearchCounts'):
print(f" MonthlySearchCounts: {idea.MonthlySearchCounts}")
if len(keyword_ideas) > 10:
print(f"\n ... and {len(keyword_ideas) - 10} more keyword ideas")
# Test 2: Get Keyword Traffic Estimates
print("\n" + "=" * 60)
print("Test 2: Getting Keyword Traffic Estimates...")
print("=" * 60)
# Build ad group estimators from keyword ideas
idea_ad_group_ids = []
for keyword_idea in keyword_ideas:
if hasattr(keyword_idea, 'AdGroupId') and keyword_idea.AdGroupId:
idea_ad_group_ids.append(keyword_idea.AdGroupId)
# Get unique ad group IDs
unique_ad_group_ids = list(set(idea_ad_group_ids))
ad_group_estimator_count = len(unique_ad_group_ids)
seed_offset = 0 if None in unique_ad_group_ids else 1
print(f"\nBuilding {ad_group_estimator_count} ad group estimators...")
# Initialize ad group estimators
ad_group_estimators = []
for index in range(ad_group_estimator_count):
ad_group_estimator = AdGroupEstimator(
keyword_estimators=[],
max_cpc=5.00
)
ad_group_estimators.append(ad_group_estimator)
# Populate keyword estimators for each ad group
for keyword_idea in keyword_ideas:
if not hasattr(keyword_idea, 'Keyword'):
continue
ad_group_id = keyword_idea.AdGroupId if hasattr(keyword_idea, 'AdGroupId') else None
# Determine the index for this keyword's ad group
if ad_group_id is not None:
try:
index = unique_ad_group_ids.index(ad_group_id)
except ValueError:
index = 0
else:
index = 0
# Create keyword estimator
suggested_bid = keyword_idea.SuggestedBid if hasattr(keyword_idea, 'SuggestedBid') and keyword_idea.SuggestedBid else None
max_cpc = suggested_bid if suggested_bid and suggested_bid > 0.04 else None
keyword = Keyword(
text=keyword_idea.Keyword,
match_type=MatchType.EXACT
)
keyword_estimator = KeywordEstimator(
keyword=keyword,
max_cpc=max_cpc
)
# Add to the appropriate ad group estimator
ad_group_estimators[index].keyword_estimators.append(keyword_estimator)
# Build campaign estimator
negative_keyword = NegativeKeyword(
text="foo",
match_type=MatchType.EXACT
)
language_criterion = LanguageCriterion(
language="English"
)
network_criterion = NetworkCriterion(
network=NetworkType.OWNEDANDOPERATEDANDSYNDICATEDSEARCH
)
location_criterion = LocationCriterion(
location_id='190' # United States
)
campaign_estimator = CampaignEstimator(
ad_group_estimators=ad_group_estimators,
daily_budget=50.00,
negative_keywords=[negative_keyword],
criteria=[language_criterion, network_criterion, location_criterion]
)
# Create the request
get_keyword_traffic_estimates_request = GetKeywordTrafficEstimatesRequest(
campaign_estimators=[campaign_estimator]
)
# Call the service
print("\nRequesting keyword traffic estimates...")
traffic_estimates_response = ad_insight_service.get_keyword_traffic_estimates(
get_keyword_traffic_estimates_request=get_keyword_traffic_estimates_request
)
campaign_estimates = traffic_estimates_response.CampaignEstimates
if not campaign_estimates or len(campaign_estimates) == 0:
print("No campaign estimates found.")
return
print(f"\nFound {len(campaign_estimates)} campaign estimate(s):")
# Display campaign estimates
for i, campaign_estimate in enumerate(campaign_estimates):
print(f"\n Campaign Estimate {i+1}:")
if hasattr(campaign_estimate, 'AdGroupEstimates') and campaign_estimate.AdGroupEstimates:
print(f" Number of Ad Group Estimates: {len(campaign_estimate.AdGroupEstimates)}")
# Show first few ad group estimates
for j, ad_group_estimate in enumerate(campaign_estimate.AdGroupEstimates[:3]):
print(f"\n Ad Group Estimate {j+1}:")
if hasattr(ad_group_estimate, 'KeywordEstimates') and ad_group_estimate.KeywordEstimates:
print(f" Number of Keyword Estimates: {len(ad_group_estimate.KeywordEstimates)}")
# Show first few keyword estimates
for k, keyword_estimate in enumerate(ad_group_estimate.KeywordEstimates[:5]):
if hasattr(keyword_estimate, 'Keyword') and keyword_estimate.Keyword:
keyword_text = keyword_estimate.Keyword.Text if hasattr(keyword_estimate.Keyword, 'Text') else 'N/A'
print(f" Keyword {k+1}: {keyword_text}")
if hasattr(keyword_estimate, 'Minimum') and keyword_estimate.Minimum:
print(f" Minimum Estimates:")
if hasattr(keyword_estimate.Minimum, 'AverageCpc'):
print(f" Average CPC: {keyword_estimate.Minimum.AverageCpc}")
if hasattr(keyword_estimate.Minimum, 'Clicks'):
print(f" Clicks: {keyword_estimate.Minimum.Clicks}")
if hasattr(keyword_estimate.Minimum, 'Impressions'):
print(f" Impressions: {keyword_estimate.Minimum.Impressions}")
if hasattr(keyword_estimate, 'Maximum') and keyword_estimate.Maximum:
print(f" Maximum Estimates:")
if hasattr(keyword_estimate.Maximum, 'AverageCpc'):
print(f" Average CPC: {keyword_estimate.Maximum.AverageCpc}")
if hasattr(keyword_estimate.Maximum, 'Clicks'):
print(f" Clicks: {keyword_estimate.Maximum.Clicks}")
if hasattr(keyword_estimate.Maximum, 'Impressions'):
print(f" Impressions: {keyword_estimate.Maximum.Impressions}")
if len(ad_group_estimate.KeywordEstimates) > 5:
print(f" ... and {len(ad_group_estimate.KeywordEstimates) - 5} more keyword estimates")
if len(campaign_estimate.AdGroupEstimates) > 3:
print(f"\n ... and {len(campaign_estimate.AdGroupEstimates) - 3} more ad group estimates")
print("\n" + "=" * 60)
print("Keyword planner test completed successfully!")
print("=" * 60)
except Exception as ex:
print(f"Error occurred: {str(ex)}")
import traceback
traceback.print_exc()
if __name__ == '__main__':
print("Loading the web service client...")
authorization_data = AuthorizationData(
account_id=None,
customer_id=None,
developer_token=DEVELOPER_TOKEN,
authentication=None,
)
authenticate(authorization_data)
ad_insight_service = ServiceClient(
service='AdInsightService',
version=13,
authorization_data=authorization_data,
environment=ENVIRONMENT,
)
main()