Due to low activity in the KeywordOptimizer project, we've decided to deprecate it on September 28, 2018. There will not be any updates for AdWords API version migrations or issue tracking after this date. Please clone or fork this repository and migrate to the latest AdWords API version if you intend to continue using the code. This repository will be removed on or after 12th January 2019.
We encourage you to own and maintain this project. Please fork or clone the repository and follow the Google Ads Developer Blog for notifications of upcoming API migrations.
Your feedback is valuable to us in shaping our products. If you have comments or suggestions, please raise these on the project’s issue page.
All the best for your future ads integrations.
Google Ads team
If you are using this project, please follow the API anouncements and API version sunsets. The AdWords API changes frequently; current versions are being sunset about 6-8 months after their introduction. Please make sure to upgrade your project around that time frame.
Please keep in mind: This tool uses the TargetingIdeaService and TrafficEstimatorService of the AdWords API. If you expose this tool directly to your clients, the complete set of required minimum functionality might apply to your application.
This tool provides estimations only, the real performance of your ads might differ substantially. Please make sure you understand the limitations of our keyword planning tools.
Please let us know if you run into issues in the project's issue tracker. This beta release may not fit your needs for production environments. We are constantly working on improving the project; your feedback is very important to us.
KeywordOptimizer is an open-source tool for finding optimized sets of keywords for AdWords, implemented in Java. The goals of this project are:
- Provide education and guidance on using the AdWords API services for keyword suggestion and traffic estimation.
- Allow non-technical users to run searches for optimized sets of keywords from the command line.
- Provide an open-source framework for keyword optimization for advanced users, which can be extended with custom implementations.
The tool implements an evolutionary process for keyword optimization, inspired by the theory of Darwinism:
- Create a set of seed keywords using a variety of parameters (such as URL, business category, location).
- Estimate traffic and derive a score for each keyword.
- Use the keywords with the highest score to generate similar or alternative keywords. Remove the keywords with the lowest scores from the set.
- Repeat this process for a number of steps or until there is no further improvement. By repeatedly "reproducing" the best and removing the worst keywords, the overall quality of the keyword set is likely to increase.
Note: This tool uses the TargetingIdeaService / TrafficEstimatorService of the AdWords API. As these services return dummy data for test accounts, this tool will not work as intended for test accounts either.
The code is organized in three separate Maven projects:
- keyword-optimizer-core contains the core library and code necessary to run the tool from the command line. Previously, all code was bundled here.
- keyword-optimizer is the parent project that encompasses both projects above as modules.
You will need Java and Maven installed before configuring the project.
$ git clone https://github.com/googleads/keyword-optimizer
$ mvn compile dependency:copy-dependencies package
The tool needs 2 configuration files (their names can be configured):
ads.properties: Parameters for interaction with the AdWords API.keyword-optimizer.properties: Parameters for the optimization process.
This tool simply passes the ads.properties file to the AdWords API Java Client library. If you're already using the AdWords API, you can reuse your existing configuration. If you're new to the API, you can follow our guide to get started.
The tool-specific configuration file specifies which classes (strategy pattern) and parameters are used during various stages of the process. If you're using this tool off-the-shelf, you probably don't need to worry about it, and can use the defaults we provide. If you are extending this project, you can plug in your own implementations here.
This is our default configuration:
# Properties for KeywordOptimizer
# Class used for finding keyword alternatives, has to implement com.google.api.ads.adwords.keywordoptimizer.AlternativesFinder.
optimizer.alternativesFinder = com.google.api.ads.adwords.keywordoptimizer.TisAlternativesFinder
# Class used for estimating keyword traffic, has to implement com.google.api.ads.adwords.keywordoptimizer.TrafficEstimator.
optimizer.estimator = com.google.api.ads.adwords.keywordoptimizer.TesEstimator
# Class used for calculating keyword scores, has to implement com.google.api.ads.adwords.keywordoptimizer.ScoreCalculator.
optimizer.scoreCalculator = com.google.api.ads.adwords.keywordoptimizer.ClicksScoreCalculator
# Class used for defining the round-based strategy, has to implement com.google.api.ads.adwords.keywordoptimizer.RoundStrategy.
optimizer.roundStrategy = com.google.api.ads.adwords.keywordoptimizer.DefaultRoundStrategy
# Maximum number of rounds
optimizer.roundStrategy.maxSteps = 3
# Minimum average score improvement per round (0 for no restriction)
optimizer.roundStrategy.minImprovement = 0
# Maximum size for the keyword population
optimizer.roundStrategy.maxPopulation = 100
# Number of best keywords to use for replication in each round
optimizer.roundStrategy.replicateBest = 5
You can run the tool using the following command. Be sure to specify the path
to the properties files above using the -ap and -kp parameters.
$ java -jar keyword-optimizer-core/target/keyword-optimizer.jar -ap keyword-optimizer-core/src/main/resources/ads.properties -kp keyword-optimizer-core/src/main/resources/keyword-optimizer.properties -m EXACT -o CONSOLE -cpc 10.0 -sk "emergency plumber"
Note: Additional required parameters are included above to show a full example of running the tool with standard parameters.
Alternatively, you can run the tool using Maven as follows.
$ mvn exec:java -Dexec.mainClass="com.google.api.ads.adwords.keywordoptimizer.KeywordOptimizer" \
-Dexec.args="-ap keyword-optimizer-core/src/main/resources/ads.properties -kp keyword-optimizer-core/src/main/resources/keyword-optimizer.properties"
You can specify the following command line options when running the tool. Running the tool without parameters will print this help screen.
usage: keyword-optimizer
-h,--help Shows this help screen.
-ap,--ads-properties <file> Location of the ads.properties file.
-cpc,--max-cpc <double> Use the given maximum CPC (in USD, e.g., 5.0
for $5).
-kp,--keyword-properties <file> Location of the keyword-optimizer.properties
file.
-lang,--languages <ids> Use the given locations IDs (ID as defined @
https://goo.gl/WWzifs) for language-targeted
results.
-loc,--locations <ids> Use the given locations IDs (ID as defined @
https://goo.gl/TA5E81) for geo-targeted
results.
-m,--match-types <types> Use the given keyword match types (EXACT,
BROAD, PHRASE).
-o,--output <mode> Mode for outputting results (CONSOLE / CSV)
Note: If set to CSV, then option -of also
has to be specified.
-of,--output-file <file> File to for writing output data (only needed
if option -o is specified).
-sc,--seed-category <id> Use the given category (ID as defined @
https://goo.gl/xUEr6s) to get keywords as a
seed for the optimization.
Note: Only one seed-* option is allowed.
-sk,--seed-keywords <keywords> Use the given keywords (separated by spaces)
as a seed for the optimization.
Note: Only one seed-* option is allowed.
-skf,--seed-keywords-file <file> Use the keywords from the given file (one
keyword per row) as a seed for the
optimization.
Note: Only one seed-* option is allowed.
-st,--seed-terms <terms> Use the given search terms (separated by
spaces) as a seed for the optimization.
Note: Only one seed-* option is allowed.
-stf,--seed-terms-file <file> Use the search terms from the given file
(one keyword per row) as a seed for the
optimization.
Note: Only one seed-* option is allowed.
-su,--seed-urls <urls> Use the given urls (separated by spaces) to
extract keywords as a seed for the
optimization.
Note: Only one seed-* option is allowed.
-suf,--seed-urls-file <file> Use the urls from the given file (one url
per row) to extract keywords as a seed for
the optimization.
Note: Only one seed-* option is allowed.
Pull requests are very much appreciated. Please sign the Google Individual Contributor License Agreement (there is a convenient online form) before submitting.
- Authors
- Timo Bozsolik (Google Inc.),
- Copyright
- Copyright © 2016 Google, Inc.
- License
- Apache 2.0
- Limitations
- This is example software, use with caution at your own risk.