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 timeframe.
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.
Build the project using Maven
$ 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
$ 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.
Running with Maven
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"
Command line options
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.