Print this articleWe'll be performing routine system maintenance on Saturday, January 10 from approximately 10:00am to 2:00pm PST. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
The AdWords API team has been hard at work on some big improvements for 2009 that we're very excited to bring you. Although we're still working on the details, we wanted to give you a preview so you can plan your programming resources accordingly.
These fundamental changes will offer you some major advantages, as well as improve our API infrastructure:
We expect to launch this new API version in the first half of 2009. Since we're introducing more changes than usual, we'll extend the normal sunset period for v13 to at least 6 months after the new version's launch. These new features, and others, are still in development, but we'll be giving you more details as soon as we have them in the new year.
Sincerely,
Doug Raymond
Product Manager, AdWords API
These fundamental changes will offer you some major advantages, as well as improve our API infrastructure:
- New calls features
- More operations in a single call: We're changing the way services are constructed so that you'll be able to accomplish more work per call. Specifically, operations will accept a variety of modifiers acting on elements across ad groups. For example, you'll be able to add, update, and delete keywords across ad groups, all within a single call.
- Asynchronous calls: We'll offer asynchronous calls, which will allow you to work with large sets of data faster and more easily. Instead of having to wait for our system to fully complete your request before you can make another one, you'll be able to make another call as soon as the API service confirms that it's received your previous call. No more waiting for large requests to be finished. (Synchronous methods will still be supported as well.)
- Partial failure acceptance: We plan to support partial failure, so large posts aren't rolled back due to a few errors. This allows you to keep moving forward with development and not have to re-do the same posts.
- Lower costs: We plan to directly reduce API units consumed for the new asynchronous methods, and are exploring other ways to improve the value you get from the AdWords API by lowering costs and/or quota use.
- Faster development: Our new codebase will allow us to expose new AdWords features faster, keeping the API more closely in line with the AdWords web interface. This will make it easier for you to keep your applications current and to take advantage of the latest AdWords advancements.
We expect to launch this new API version in the first half of 2009. Since we're introducing more changes than usual, we'll extend the normal sunset period for v13 to at least 6 months after the new version's launch. These new features, and others, are still in development, but we'll be giving you more details as soon as we have them in the new year.
Sincerely,
Doug Raymond
Product Manager, AdWords API
Just a friendly heads-up to developers out there: when you send SOAP requests to the Production AdWords API service, you should be connecting to the adwords.google.com hostname. (Requests to the AdWords API Sandbox should be sent to sandbox.google.com.)
If you're using one of our client libraries or generate your own client code using the standard WSDL definitions then you should already be doing the right thing. Your requests will automatically be sent to a URL starting with https://adwords.google.com/api/adwords/. Our logs show that the overwhelming majority of incoming traffic falls into this category.
If you're using one of our client libraries or generate your own client code using the standard WSDL definitions then you should already be doing the right thing. Your requests will automatically be sent to a URL starting with https://adwords.google.com/api/adwords/. Our logs show that the overwhelming majority of incoming traffic falls into this category.
However, if you've gone out of your way to specifically send your traffic to a hostname other than adwords.google.com, or directly to a specific IP address, please note that they'll stop accepting AdWords API traffic in the near future. If you think that you might be sending to a non-standard hostname, then please take the time to remediate your code.
Managing your bids is crucial to running a successful AdWords campaign. The AdWords API offers developers control over all aspects of their bidding strategy, but the variety of options available can be daunting. To add to this, AdWords added support for mixed keyword and website criteria within the same ad group several months ago. In the interest of answering some common questions, here are a few ad group structures and the way to implement them using the AdWords API.
CPC bidding
Getting the right setup
The AdWords API can be used to manage both keyword and website criteria within the same ad group. However, you do need to make sure your ad groups are properly configured before they'll accept both those criteria types. In order for your ad group to accept keyword criteria, it must have its keywordMaxCpc and/or keywordContentMaxCpc attributes set to your maximum CPC bid. In order for your ad group to accept website criteria, the siteMaxCpc attribute needs to be set as well. Failing to have a value set for siteMaxCpc is a common cause of SOAP errors of type 74 while trying to add website criteria to an existing ad group. In fact, a misleading message may appear: "This criterion type is invalid. Acceptable values are 'Website' and 'Keyword'. Websites and keywords may not be used in ad groups in the same campaign." Rest assured, the spelling of "Website" did not change overnight. You may just need to set your siteMaxCpc value.
Which bid gets triggered?
Although controlling both keywords and websites within the same ad group adds a new range of possibilities for campaign structure, it can be confusing as to which bid will be triggered under different situations. This information is available in this article in the AdWords Help Center but it helps to visualize a few common scenarios.
For the following examples, let's suppose that we have added the keywords "Mars" and "rover" as well as the website "nasa.org" to our ad group. In our campaign we have set the bidding strategy to CPC and have enabled our ads to appear on Google search, Search partners, and Relevant pages across the entire network.
(By the way, if you're curious about which bid will get used if an ad is triggered by both a keyword and a website in the same ad group, it will always be the bid associated with your website.)
CPM bidding
CPC bidding
Getting the right setup
The AdWords API can be used to manage both keyword and website criteria within the same ad group. However, you do need to make sure your ad groups are properly configured before they'll accept both those criteria types. In order for your ad group to accept keyword criteria, it must have its keywordMaxCpc and/or keywordContentMaxCpc attributes set to your maximum CPC bid. In order for your ad group to accept website criteria, the siteMaxCpc attribute needs to be set as well. Failing to have a value set for siteMaxCpc is a common cause of SOAP errors of type 74 while trying to add website criteria to an existing ad group. In fact, a misleading message may appear: "This criterion type is invalid. Acceptable values are 'Website' and 'Keyword'. Websites and keywords may not be used in ad groups in the same campaign." Rest assured, the spelling of "Website" did not change overnight. You may just need to set your siteMaxCpc value.
Which bid gets triggered?
Although controlling both keywords and websites within the same ad group adds a new range of possibilities for campaign structure, it can be confusing as to which bid will be triggered under different situations. This information is available in this article in the AdWords Help Center but it helps to visualize a few common scenarios.
For the following examples, let's suppose that we have added the keywords "Mars" and "rover" as well as the website "nasa.org" to our ad group. In our campaign we have set the bidding strategy to CPC and have enabled our ads to appear on Google search, Search partners, and Relevant pages across the entire network.
- A user searches for the phrase "Mars rover" within Google or on one of Google's search partners. AdWords will always use the keywordMaxCpc bid to determine if your ad should be placed.
- A user visits NASA's new Mars rover website with nasa.org as the domain. In this case, because you have nasa.org as one of your Website criteria, the bid will be either be the siteMaxCpc value from the ad group or the maxCpc from the Website criteria. If there's a maxCpc value defined in the criteria, then it will take precedence. Even if this website would trigger the keywords in your ad group, the placement-related bidding values will always take precedence as they're considered more specific.
- A user visits the Mars rover's manufacturer's website, which happens to be on the content network (i.e. it is an AdSense enabled website). The keyword criteria "Mars rover" is what ends up triggering the ad. In this case, AdWords will first check the maxCpc value set for the keyword that triggered the ad, if this is not set, the keywordContentMaxCpc value from the ad group will be used. If keywordContentMaxCpc is not set, it will use the keywordMaxCpc value. It will not under any circumstance use the siteMaxCpc value.
(By the way, if you're curious about which bid will get used if an ad is triggered by both a keyword and a website in the same ad group, it will always be the bid associated with your website.)
CPM bidding
If you've set up your campaign for CPM bidding (because you'll be running image or video ads on the Content network, and not text ads on the Search network), then the only relevant ad group bid setting to configure is siteMaxCpm. This simplifies setup considerably compared to the options available when you're using CPC bidding.
You can add both keyword and website criteria to the same ad group, and the siteMaxCpm bid will always be used when determining what you're willing to bid for each impression your ad receives.
Both keywords and website criteria will be able to trigger your ad in the Content network, with the caveat that your keyword criteria won't generate any impression or click-related statistics when used to trigger ads in the Content network.
--Adam Rogal and Jeffrey Posnick, AdWords API Team
We'll be performing routine system maintenance on Saturday, November 8 from approximately 10:00am to 2:00pm PST. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
AdWords API v13 ushered in a number of great new features, like exposing keyword quality score information, new report types, and support for more geo-targeting options. There is an additional new feature that received somewhat less fanfare, though: starting with v13, the getKeywordVariations() method of the Keyword Tool Service returns information about the average and last month's search volume for each suggested keyword variation. Ever since this feature was rolled out in the standalone Keyword Tool web page in July we've been hearing requests from developers eager to get that sort of information from the AdWords API, so we thought it would be worthwhile to explain how you can now retrieve similar data from your own code.
Let's say you're considering adding the keyword new york to one of your ad groups, and you're curious about what kind of search volume that keyword normally receives. You're interested in data pertaining to English-language queries in the United States and Canada, and you want data about that exact keyword--not any of its synonyms. In order to retrieve that search volume data, the following SOAP request body would be appropriate:
<Body>
<getKeywordVariations>
<seedKeywords>
<negative>false</negative>
<text>new york</text>
<type>Broad</type>
</seedKeywords>
<useSynonyms>false</useSynonyms>
<language>en</language>
<countries>US</countries>
<countries>CA</countries>
</getKeywordVariations>
</Body>
If you make that SOAP request to the AdWords API v13, you'll get a (large) number of results back--around 200 potential variations on the keyword new york, like new york hotels or brooklyn new york. Each variations will have its own set of search volume data associated with it, and that data is all potentially useful. For the purposes of this example, though, what we're interested in is seeing the search volume data for our seed keyword of new york. Your original seed keyword(s) will always be included in the results you get back from getKeywordVariations(), so your code can loop through the results until it finds the one that matches your original request. In this case, the XML for the result entry looks like:
<moreSpecific>
<text>new york</text>
<language>en</language>
<advertiserCompetitionScale>5</advertiserCompetitionScale>
<avgSearchVolume>68000000</avgSearchVolume>
<lastMonthSearchVolume>83100000</lastMonthSearchVolume>
</moreSpecific>
So now we know, that over the past twelve months, the average monthly search volume for the keyword new york was 68,000,000 queries, and last month the search volume made it all the way up to 83,100,000 queries. New York is a popular town!
Hopefully the additional data returned by the getKeywordVariations() method in AdWords API v13 will make it even easier to target and optimize your AdWords campaigns.
--Jeffrey Posnick, AdWords API Team
Let's say you're considering adding the keyword new york to one of your ad groups, and you're curious about what kind of search volume that keyword normally receives. You're interested in data pertaining to English-language queries in the United States and Canada, and you want data about that exact keyword--not any of its synonyms. In order to retrieve that search volume data, the following SOAP request body would be appropriate:
<Body>
<getKeywordVariations>
<seedKeywords>
<negative>false</negative>
<text>new york</text>
<type>Broad</type>
</seedKeywords>
<useSynonyms>false</useSynonyms>
<language>en</language>
<countries>US</countries>
<countries>CA</countries>
</getKeywordVariations>
</Body>
If you make that SOAP request to the AdWords API v13, you'll get a (large) number of results back--around 200 potential variations on the keyword new york, like new york hotels or brooklyn new york. Each variations will have its own set of search volume data associated with it, and that data is all potentially useful. For the purposes of this example, though, what we're interested in is seeing the search volume data for our seed keyword of new york. Your original seed keyword(s) will always be included in the results you get back from getKeywordVariations(), so your code can loop through the results until it finds the one that matches your original request. In this case, the XML for the result entry looks like:
<moreSpecific>
<text>new york</text>
<language>en</language>
<advertiserCompetitionScale>5</advertiserCompetitionScale>
<avgSearchVolume>68000000</avgSearchVolume>
<lastMonthSearchVolume>83100000</lastMonthSearchVolume>
</moreSpecific>
So now we know, that over the past twelve months, the average monthly search volume for the keyword new york was 68,000,000 queries, and last month the search volume made it all the way up to 83,100,000 queries. New York is a popular town!
Hopefully the additional data returned by the getKeywordVariations() method in AdWords API v13 will make it even easier to target and optimize your AdWords campaigns.
--Jeffrey Posnick, AdWords API Team
We're happy to announce the release of the AdWords API version 13 (v13)! V13 introduces several changes to the AdWords API; we've highlighted the main points below. For a complete list of v13 changes, please see our release notes.
V13 Highlights
V12 Sunset in 2009
V13 Highlights
- New geotargeting options: Target multiple geographic levels (countries, regions, metro areas, and cities) within a single campaign, target specific regions of multiple countries in a single campaign, and setup negative targeting for specific regions (for example, target the United States with the exception of Alaska).
- New reports: Generate Search Query Performance and Geographic Performance reports using ReportService and DefinedReportJob.
- Mobile image ads: Use the new MobileImageAd ad type to create graphical advertisements for the mobile content network.
- Suggested campaign budgets: Retrieve budget suggestions for your campaigns with
getRecommendedBudgetList. - Active campaigns and ad groups: Want to retrieve only your active campaigns and ad groups? Now you can, using
getActiveAdWordsCampaignsandgetActiveAdGroups. - Quality-based bid and Quality Score support: We've added two new
Keywordfields: firstPageCpc(first page bid estimate)qualityScore(Quality Score of the keyword)
Per our versioning policy, v12 will be supported for four months from today, after which time it will be turned off. Therefore, please make sure that you upgrade to v13 before February 20th, 2009. As with every new version of the AdWords API, we strongly encourage you to review the Release Notes section of the Developer's Guide to learn more about this version.
We know the holiday season is a busy time for advertisers and often means a number of updates to your campaigns. We'd like to help out by providing you with more API units.
Starting now and extending through January 15th of next year, all developers will receive a bonus of 20% more API units at no additional cost.
As always, we encourage you to use the API as efficiently as possible. For instance, we recommend using list methods (e.g. addCampaignList) whenever appropriate because they're the most cost-effective way to process large data sets. See our blog post on efficient software to learn other ways to get more out of your API units. For more general API best practices, see our previous post dedicated to just that topic.
Happy Holidays,
-Adam Wooley, Product Marketing
Starting now and extending through January 15th of next year, all developers will receive a bonus of 20% more API units at no additional cost.
- All developers can purchase API units at the rate of 1200/$0.25, up from 1000/$0.25, from now through January 15th, 2009.
- Advertisers who are eligible for free API units will receive credit at the rate 300/$ of AdWords spend, up from 250/$ of AdWords spend. They will be credited the holiday bonus based on their spend in previous months.
As always, we encourage you to use the API as efficiently as possible. For instance, we recommend using list methods (e.g. addCampaignList) whenever appropriate because they're the most cost-effective way to process large data sets. See our blog post on efficient software to learn other ways to get more out of your API units. For more general API best practices, see our previous post dedicated to just that topic.
Happy Holidays,
-Adam Wooley, Product Marketing
We'll be performing routine system maintenance on Saturday, October 18 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
Welcome to part 5 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In our previous episode, we discussed SOAP errors related to failed validations. Today we'll discuss SOAP errors related to syncing errors and concurrent changes. You can find links to our earlier posts here: Part 1, Part 2, Part 3, Part 4.
Syncing Errors
Some of the common ApiErrors are "Missing a required field", "Wrong value for a field", etc. They are often self-explanatory, so it's easy to spot the error. However, two errors are trickier to spot:
- The client asked us to load an entity but no entity with that ID was found. (Error code 5)
- The client does not have permission to perform the requested operation. (Error code 4)
Both these errors occur among developers who store their AdWords campaigns, ads, etc. in a local database. While storing your campaigns and ads in local database helps to boost performance in your application (and at times help integration with other campaign management systems), your local database might be out of sync with your AdWords account for several reasons, which would cause these errors.
Common causes of your database being out of sync with your account are that the client updated some campaigns using the AdWords website, or that you have a bug in the code that's inserting the wrong records into your local database.
Both the ApiErrors mentioned above take more specific forms, and the detail, field, and trigger properties of the ApiError node should help you find out the cause behind the issue. For example, the following SOAP fault was generated while trying to update a Campaign that does not exist (Campaign ID: 0):
<soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Server.userException</faultcode>
<faultstring>One or more input elements failed validation.</faultstring>
<detail>
<ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v12">
<ns1:code>122</ns1:code>
<ns1:message>One or more input elements failed validation.</ns1:message>
<ns1:errors>
<ns1:index>0</ns1:index>
<ns1:field>campaignId</ns1:field>
<ns1:trigger>0</ns1:trigger>
<ns1:code>5</ns1:code>
<ns1:isExemptable>false</ns1:isExemptable>
<ns1:detail>No Campaign with this ID was found.</ns1:detail>
</ns1:errors>
</ns1:fault>
</detail>
</soapenv:Fault>
</soapenv:Body>
Note how the error took a specific form (Error code = 5, detail = No campaign with this id was found, field = campaignId, trigger = 0).
<soapenv:Fault>
<faultcode>soapenv:Server.userException</faultcode>
<faultstring>One or more input elements failed validation.</faultstring>
<detail>
<ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v12">
<ns1:code>122</ns1:code>
<ns1:message>One or more input elements failed validation.</ns1:message>
<ns1:errors>
<ns1:index>0</ns1:index>
<ns1:field>campaignId</ns1:field>
<ns1:trigger>0</ns1:trigger>
<ns1:code>5</ns1:code>
<ns1:isExemptable>false</ns1:isExemptable>
<ns1:detail>No Campaign with this ID was found.</ns1:detail>
</ns1:errors>
</ns1:fault>
</detail>
</soapenv:Fault>
</soapenv:Body>
Note how the error took a specific form (Error code = 5, detail = No campaign with this id was found, field = campaignId, trigger = 0).
Similarly, the SOAP fault shown below was generated while trying to retrieve a Campaign (Campaign ID : 111111) that my MCC doesn't have access to.
<soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Server.userException</faultcode>
<faultstring>Either this object does not exist, or this user does not have permission to access it.</faultstring>
<detail>
<ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v12">
<ns1:code>4</ns1:code>
<ns1:message>Either this object does not exist, or this user does not have permission to access it.</ns1:message>
<ns1:trigger>111111</ns1:trigger>
</ns1:fault>
</detail>
</soapenv:Fault>
</soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Server.userException</faultcode>
<faultstring>Either this object does not exist, or this user does not have permission to access it.</faultstring>
<detail>
<ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v12">
<ns1:code>4</ns1:code>
<ns1:message>Either this object does not exist, or this user does not have permission to access it.</ns1:message>
<ns1:trigger>111111</ns1:trigger>
</ns1:fault>
</detail>
</soapenv:Fault>
</soapenv:Body>
Concurrent Changes
Finally, if you are writing multithreaded applications, or if multiple persons are using your application at the same time, you may come across the error "The Attempted modification failed due to changes made concurrently by another agent or user. (Error code 58)." To avoid this error, make sure your applications are properly synchronized, so that no two threads/instances of your application modifies the same campaign, ad group, ad, etc. at the same time.
You could also run into this error if two programs are modifying the same campaign, ad group or ad at the same time. For example, you could run into this error if 2 people are modifying the same campaign, ad, etc. using the AdWords Front End and AdWords Editor, or even 2 instances of your Application.
Debugging SOAP faults can be frustrating sometimes. We hope these tips will help you in figuring out common issues and save time for something that is more fun -- coding!
--Anash Oommen, AdWords API Team
Welcome to part 4 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In our previous episode, we discussed possible causes for "operation does not exist" errors. Today we'll discuss SOAP errors on failed validations. You can find links to our earlier posts here: Part 1, Part 2, Part 3.
Failed Validation
A more generic error is "One or more input elements failed validation. (Error code 122)". In this case, the detail field of the response will contain a sequence of ApiError elements itemizing the validation errors found. The following fields may be specified:
- index: indicates the index of the element in the input array that caused the violation
- code: indicates the type of violation
- field: the input element field name that contains the violation
- trigger: a string describing the violation that triggered the error
- isExemptable: a boolean indicating whether it is possible to get an exemption for this kind of violation or not. The default is false
- textIndex: where in the text the violation occurred
- textLength: the length of the string that caused the violation
- detail: why the violation occurred
A common error that falls under this category is an Ad Policy violation. You receive an "The text specified for this Creative violates Google policy. (Error code 21)" error if you try to add an Ad that does not comply with Google’s Ad policy. To avoid getting this error, make sure that you check your Ads for policy violation using checkAds() before adding Ads using addAd(). If an Ad violates a policy, then checkAds() will return a sequence of ApiError objects that describe the policy violation. You can examine the details field to check what caused the policy violation. Also, some policy violations may be exemptable, and the isExemptable will be set as true if a policy violation is exemptable. If set, you can request for a policy exemption while adding this Ad.
Next time, we will explore errors that arise while syncing accounts, or performing concurrent requests to AdWords API.
--Anash Oommen, AdWords API Team
Today, we're pleased to announce the AdWords API Local Database Sync project. The scripts that make up the project can be used to schedule reports using the AdWords API, store the results in a local database (using SQLite), and then run queries against the database.
If you recall, one of the recommendations listed on our recent list of "AdWords API: Top Ten Practices" extolled the virtues of maintaining your AdWords account information in a local database, and using the AdWords API to keep that information up to date. Querying a local database offers speed and cost advantages compared to making repeated AdWords API calls when answering questions like "How many active AdWords campaigns do I have across all my accounts?" Maintaining a local database with historical information can also help you answer questions that the AdWords API alone can't, like "Which keywords were updated in my accounts during the past week?" Now, with the AdWords API Local Database Sync you can answer these questions.
Here are some of the technical details: The scripts are written in Python, and make use of the SOAPpy libraries for accessing the AdWords API SOAP service. The Python code is written against the dbapi2 database API, and by default it will use the SQLite implementation and store the report data in a SQLite database file on the local file system. It's possible to swap out the SQLite libraries for another database library that supports the dbapi2 interface.
While some developers may have already written their own in-house AdWords database synchronization code, we wanted to provide a standalone, open source solution for those developers who don't yet have such a system in place. We're also hopeful that the code serves as a helpful example of scheduling and parsing AdWords API reports, and that even folks who are already maintaining their own databases will get something out of the project.
Visit the project's home on Google Code and give it a try!
Cheers,
-Jeffrey Posnick, AdWords API Team
If you recall, one of the recommendations listed on our recent list of "AdWords API: Top Ten Practices" extolled the virtues of maintaining your AdWords account information in a local database, and using the AdWords API to keep that information up to date. Querying a local database offers speed and cost advantages compared to making repeated AdWords API calls when answering questions like "How many active AdWords campaigns do I have across all my accounts?" Maintaining a local database with historical information can also help you answer questions that the AdWords API alone can't, like "Which keywords were updated in my accounts during the past week?" Now, with the AdWords API Local Database Sync you can answer these questions.
Here are some of the technical details: The scripts are written in Python, and make use of the SOAPpy libraries for accessing the AdWords API SOAP service. The Python code is written against the dbapi2 database API, and by default it will use the SQLite implementation and store the report data in a SQLite database file on the local file system. It's possible to swap out the SQLite libraries for another database library that supports the dbapi2 interface.
While some developers may have already written their own in-house AdWords database synchronization code, we wanted to provide a standalone, open source solution for those developers who don't yet have such a system in place. We're also hopeful that the code serves as a helpful example of scheduling and parsing AdWords API reports, and that even folks who are already maintaining their own databases will get something out of the project.
Visit the project's home on Google Code and give it a try!
Cheers,
-Jeffrey Posnick, AdWords API Team
Welcome to part 3 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In our previous episodes, we discussed how an invalid developer token or a missing SOAP header can lead to SOAP faults. Today we cover missing operations and methods.
Operation Doesn’t Exist
Developers may also come across the error “The request body did not contain an operation or the specified operation does not exist. (Error code 116)."
- The most obvious reason for this error is that the method you called does not exist in the webservice you called. This could happen due to a mistyped method name (e.g. GetAccountInfo instead of getAccountInfo) in your SOAP request. This could also happen because you sent your SOAP request to the wrong web service.
- You could also get this error if you mentioned a wrong namespace against your method. For example, For example, the following call to https://adwords.google.com/api/adwords/v12/AccountService will cause the error:
<soap:Body>
<getAccountInfo xmlns="https://adwords.google.com/api/adwords/v11"/>
</soap:Body>
<getAccountInfo xmlns="https://adwords.google.com/api/adwords/v11"/>
</soap:Body>
AdWords API will ignore all nodes that do not match its namespace, and trigger the error in this case.
Next time, we'll explore errors that result from failed validations and policy errors.
Welcome to part 2 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In the last episode, we discussed how using an invalid Developer token could lead to SOAP faults. Now, below, we'll talk about dealing with missing headers in your SOAP requests.
No Header
New developers are also likely to get the error "The client request did not contain a [header type] header." (Error code 1, 2, 8...).
- If you get this error, the most obvious reason is that you haven’t mentioned a required SOAP header in your request XML. Each SOAP request requires the following headers: "email", "password", "developerToken", "applicationToken", and "useragent". In addition, you may also need to include the "clientEmail" or "clientCustomerId" header, depending on the API method you’re calling.
- Another possible reason for getting this error is that you have mentioned all the required headers, but have provided the wrong XML namespace in your XML. For example, if you send the following header request to https://adwords.google.com/api/adwords/v12/AccountService, you will get the error that email header was missing.
<soap:Header>
<email xmlns="https://adwords.google.com/api/adwords/v11">INSERT_YOUR_ EMAIL _HERE</email>
<!--more nodes-->
</soap:Header>
- The best way to fix this issue is to turn on SOAP XML logging and check your SOAP request XML for missing header values. A well-formed SOAP request message looks something like this:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<soap:Header>
<applicationToken xmlns="https://adwords.google.com/api/adwords/v12">INSERT_APPLICATION_TOKEN_HERE</applicationToken>
<developerToken xmlns="https://adwords.google.com/api/adwords/v12">INSERT_DEVELOPER_TOKEN_HERE</developerToken>
<email xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_EMAIL_HERE</email>
<password xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_PASSWORD_HERE</password>
<useragent xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_USERAGENT_HERE</useragent>
</soap:Header>
<soap:Body>
<getAccountInfo xmlns="https://adwords.google.com/api/adwords/v12"/>
</soap:Body>
</soap:Body>
</soap:Envelope>
If you are using AdWords API code samples, then the headers are mentioned within the source code itself. If you are using an AdWords API client library, then the headers are often mentioned in an appropriate configuration file. The .NET client library uses app.config, the Java and Ruby client libraries use adwords.properties file and APIlity uses authentication.ini to store the header values. The Python library uses auth.pkl. You can inspect these files to see if the required headers are mentioned in the configuration files. Finally, all the client libraries have an appropriate constructor, which can accept the required headers and initialize the library, so you might want to inspect the code that initializes the library as well.
Next time, we'll explore errors related missing API operations and methods.
--Anash Oommen, AdWords API Team
--Anash Oommen, AdWords API Team
As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. We thought it would be useful to go over the most common SOAP faults that you might encounter while making AdWords API calls. To keep things fresh, we also decided to try a new format -- a series of posts. Hope you like it!
Invalid Developer Token
The most common error, encountered by developers making API calls for the first time, is "The developer token is invalid." (Error code 42). There are couple of main reasons you may get this error.
- If this is your first time making the call, make sure that you’re making calls to the account in production environment (adwords.google.com) rather than the AdWords API sandbox (sandbox.google.com). API sample code is configured by default to send the requests to sandbox account and not production account. Thus, if you started programming using this code, this is the most likely reason for the error.
- Similarly, if you are using an AdWords API client library, they are also configured by default to send request to the AdWords API sandbox. If you are using Java, .NET or Ruby client libraries, make sure that you haven’t provided "alternateUrl" key as part of user credentials in the configuration file (adwords.properties or app.config). For Apility library, make sure that Use_Sandbox key is set as ‘No’ in settings.ini file. For python client library, make sure you haven't provided an argument server="'https://sandbox.google.com'" when initializing service class. Also, each library has an appropriate constructor which will accept the credentials as parameters while initializing the library. Make sure that you haven’t provided “alternateUrl” here as well. Finally, some libraries might provide utility functions (e.g. .NET client library provides useSandbox()) that will allow you to switch between production and sandbox accounts at runtime. Make sure that these functions are not called in your code.
- A less common, but more obvious, reason for this error is that the token in your code is invalid. The chance of this happening is low, since most developers copy their token from their MCC account. Nevertheless, it could happen if you’ve mistakenly swapped the application and developer tokens, or if you’ve reset the developer token in your account but forgotten to update your code. Double checking your code should help you spot the reason for the error.
Next time, we'll explore errors related to missing headers in SOAP requests. Keep an eye on the blog for upcoming posts.
--Anash Oommen, AdWords API Team
We'll be performing routine system maintenance on Saturday, September 13 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
Cutting API calories from your app
One of the questions we often get asked by developers is how to spend fewer API units; if you're not careful, you might end up wasting a lot unnecessarily. Thankfully, you should be able to curb your software's appetite with a few simple suggestions:
- Two ways to get there
Do you run a lot of campaigns across your client accounts? If so, you might want to schedule Campaign Performance reports instead of using the getCampaignStats method of the Campaign Service. Conversely, if you keep few campaigns, the second option is probably better.
- Bird's-eye view
Sometimes you just need to retrieve a big chunk of an account's data, with few details. If you've got a lot of campaigns, ad groups, ads, or keywords, it might be a good idea to schedule a Structure report instead. That will give you a nice list of what you're looking for in a much more scalable approach.
- Schedule once, run forever
If you often need the same report, you might want to consider scheduling a periodic report via the AdWords website. It will automatically get generated every day, every week, or every month, and
all you have to do is retrieve it with the Report Service methods.
- Look before you leap
Whenever you submit a new ad or criterion, you should always validate it first. It's true that the validation method has a cost too, but it's significantly smaller than the cost of failing the submission.
- Can I have the list?
After reading the previous item, you might be thinking that it's a good idea to only submit one item at a time. Actually, you have no benefit in doing so, because in a failed call you only get charged for the items that did in fact fail. You should always submit lists of items, since that's how our system is optimized to work -- give it a bunch of data and it will happily take care of it for you.
- Find the differences
A common mistake when updating items (ads, criteria, etc.) is to include items that haven't actually been changed. This will add to your costs, with no benefit! A simple way of making sure this doesn't happen is to keep two separate lists of items in your software: one before modification, and one after. Before submitting the changes to the service, just compare the two and remove the identical items.
- No one's looking for that
Keywords are what advertising on the search network is all about. If you have the right keywords, people will find you. If you don't, business will be slow. Consider for a moment how many poorly performing keywords you have. Every time you retrieve them, update them, or check their statistics via the API, you spend units. One very good way of saving units in the long run is to make sure that you go for the best, and skip the rest. One of the easiest ways of doing this is to use the Traffic Estimator Service before you add them, in order to get an idea of how much traffic those keywords would generate.
- Go play in the sandbox
Are you still developing your application, or trying out some new functionality? Well, no need to be spending any units. After all, playing should be free! We've got a sandbox ready for you to test your code during development which is free and open to anyone, so you can hack away without worrying about how many times you've tried to get that right.
- Check the price before you buy
Finally, you should keep in mind the cost of the various API methods, so that you don't run into any surprises after running your software. The latest rate sheet is always available at this page.
Have you come across any other useful tricks to keep API usage costs down? If so, share with others!
Cheers,
-Sérgio Gomes, AdWords API Team
One of the questions we often get asked by developers is how to spend fewer API units; if you're not careful, you might end up wasting a lot unnecessarily. Thankfully, you should be able to curb your software's appetite with a few simple suggestions:
- Two ways to get there
Do you run a lot of campaigns across your client accounts? If so, you might want to schedule Campaign Performance reports instead of using the getCampaignStats method of the Campaign Service. Conversely, if you keep few campaigns, the second option is probably better.
- Bird's-eye view
Sometimes you just need to retrieve a big chunk of an account's data, with few details. If you've got a lot of campaigns, ad groups, ads, or keywords, it might be a good idea to schedule a Structure report instead. That will give you a nice list of what you're looking for in a much more scalable approach.
- Schedule once, run forever
If you often need the same report, you might want to consider scheduling a periodic report via the AdWords website. It will automatically get generated every day, every week, or every month, and
all you have to do is retrieve it with the Report Service methods.
- Look before you leap
Whenever you submit a new ad or criterion, you should always validate it first. It's true that the validation method has a cost too, but it's significantly smaller than the cost of failing the submission.
- Can I have the list?
After reading the previous item, you might be thinking that it's a good idea to only submit one item at a time. Actually, you have no benefit in doing so, because in a failed call you only get charged for the items that did in fact fail. You should always submit lists of items, since that's how our system is optimized to work -- give it a bunch of data and it will happily take care of it for you.
- Find the differences
A common mistake when updating items (ads, criteria, etc.) is to include items that haven't actually been changed. This will add to your costs, with no benefit! A simple way of making sure this doesn't happen is to keep two separate lists of items in your software: one before modification, and one after. Before submitting the changes to the service, just compare the two and remove the identical items.
- No one's looking for that
Keywords are what advertising on the search network is all about. If you have the right keywords, people will find you. If you don't, business will be slow. Consider for a moment how many poorly performing keywords you have. Every time you retrieve them, update them, or check their statistics via the API, you spend units. One very good way of saving units in the long run is to make sure that you go for the best, and skip the rest. One of the easiest ways of doing this is to use the Traffic Estimator Service before you add them, in order to get an idea of how much traffic those keywords would generate.
- Go play in the sandbox
Are you still developing your application, or trying out some new functionality? Well, no need to be spending any units. After all, playing should be free! We've got a sandbox ready for you to test your code during development which is free and open to anyone, so you can hack away without worrying about how many times you've tried to get that right.
- Check the price before you buy
Finally, you should keep in mind the cost of the various API methods, so that you don't run into any surprises after running your software. The latest rate sheet is always available at this page.
Have you come across any other useful tricks to keep API usage costs down? If so, share with others!
Cheers,
-Sérgio Gomes, AdWords API Team
We'll be performing routine system maintenance on Saturday, August 23 from approximately 10:00am to 4:00pm PDT (note the 4:00pm PDT end time). You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
In accordance with our policy of sunsetting older versions of the AdWords API, we will turn off access to version 11 of the API on Tuesday, August 26, 2008. Version 12 of the API has been available for over four months now, and supports a number of new features. We hope that you've already taken the opportunity to upgrade your code.
The latest versions of the publicly available client libraries all support version 12 of the API, so if you're using one of those, please check the relevant README file for information on how to switch from version 11 to 12. The migration process should be fairly straightforward, but one thing in particular to watch out for is that ad group ids are no longer ints; they're now longs in version 12.
As always, if you have any questions about the AdWords API or upgrading to our latest versions, you can check out our Frequently Asked Questions or ask them in our developer forum.
Cheers,
-Jeffrey Posnick, AdWords API Team
We'll be performing routine system maintenance on Saturday, August 9 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
We want to give developers a heads-up about an upcoming change affecting AdWords reports. If you retrieve reports via the AdWords API's getReportDownloadUrl() or getGzipReportDownloadUrl() method then these changes may potentially affect the data in your reports. These changes impact a small number of columns and should not fundamentally change the way you parse report data.
We plan on rolling out these changes on Tuesday, August 19.
The values returned by the following columns will be changing. Please note that some of these columns are only available for reports scheduled via the AdWords web interface, not the AdWords API, but we're listing them here in case you use the AdWords API to retrieve and process such reports.
There are also fixes to edge cases in which values for the impressions and the position preferences columns that were previously returned as invalid values should be more accurate.
If you would like to test your application against these changes ahead of time, please visit the AdWords web interface and log in as an account in which you normally would run reports. Visit the "Reports" or "Client Reports" tab, select an existing report from the list, and when viewing the report, use the "Export Report" button to download the report as a .xml file. This XML should match the report XML that you will retrieve via the AdWords API after the changes are put in place.
We plan on rolling out these changes on Tuesday, August 19.
The values returned by the following columns will be changing. Please note that some of these columns are only available for reports scheduled via the AdWords web interface, not the AdWords API, but we're listing them here in case you use the AdWords API to retrieve and process such reports.
- CustomerTimeZone: the time zone information will be returned as, e.g., the previous "America/New_York" will change to "(GMT-05:00) Eastern Time".
- Time aggregation columns: the columns representing the aggregation time period (e.g. weekStart) will represent date ranges in a different format. E.g. the previous "2008-06-01-2008-06-01" will now be returned as "6/1/08 - 6/1/08".
- Keyword: values for category-based website criteria will change from, e.g., "docvertical::3" to "Animals >> Endangered Species". Values returned for keyword or non-category-based website criteria should not change.
- Interactions: the name of reported interactions will change from, e.g., "VideoPlayTime25" to "Video Play Reached 25%."
There are also fixes to edge cases in which values for the impressions and the position preferences columns that were previously returned as invalid values should be more accurate.
If you would like to test your application against these changes ahead of time, please visit the AdWords web interface and log in as an account in which you normally would run reports. Visit the "Reports" or "Client Reports" tab, select an existing report from the list, and when viewing the report, use the "Export Report" button to download the report as a .xml file. This XML should match the report XML that you will retrieve via the AdWords API after the changes are put in place.
We'll be performing routine system maintenance on Saturday, July 19 from approximately 10:00am to 3:00pm PDT (one hour longer than usual). You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
by Matt Matyas, Google Sales Engineer
Recently the API team got together to think about ways you can get the most out the AdWords API. If you're new to the AdWords API, or even a longtime user, we hope you’ll find these tips useful.
1) Stay in touch
Want to know about the newest releases, options, and features in the AdWords API? Check out the following resources, where you can hear from us and interact with other developers:
- Website: Find all AdWords API documentation and related resources.
- Blog: Stay up-to-date with latest developments and best practices.
- Mailing List: Receive important service announcements and updates by signing up at our website.
- Forum: Interact with an active community of AdWords API developers and users, whether you're finding answers and solutions or providing them.
2) Keep current with versioning
Through our versioning, we're continually offering added functionality to the AdWords API, as well as making changes to its existing functionality. Migrate your code to newer versions, and you can take advantage of the latest features. In addition, staying up-to-date with the versioning via our website or mailing list is a great way to make sure your functionality won't unexpectedly go dark as we sunset old versions. When sunsetting any version of the AdWords API, we give months of advance notice so you have plenty of time to upgrade.
3) Manage your API Units
The AdWords API uses an API Units System to distribute our resources fairly among our many users and ensure reliability for all. Understanding your AdWords API Units usage over time via the following resources will allow you to budget according to your needs:
- AdWords API Center: Sign in to your AdWords MCC account and visit the AdWords API Center to view your current usage and, if available, allocations.
- AdWords API's Info Service: Using this service through the AdWords API allows you to programmatically keep watch over your API Unit levels. This can be a great way to monitor your usage automatically, and even take action based on your data. For example, you could write a program to email your team if remaining units fall below a certain threshold.
Another best practice in API Unit management is to analyze your expected AdWords API usage and forecast expected unit implications. Our rate sheet tells how many API Units are consumed per operation. By inspecting historical usage patterns and estimating API Unit implications for future AdWords API projects you may employ, you can accomplish your goals while working within your API Unit allocations.
4) Test in the sandbox
Want a place to test without consuming API units? Use the AdWords API Sandbox environment to test out your applications without consuming API Units. The sandbox replicates the API of the live site so you can test and debug new code, allowing you to develop solid applications without any risk of harming live data.
5) Use reports
How do you gauge how your campaigns are doing? Reporting can give you all of the essential statistics you need, with minimal API Unit costs. Reporting can help you conveniently analyze many aspects of your campaigns, from structure to performance. Some examples:
- Many advertisers find value in using reports to understand performance of their keywords; values such as clicks and costs can be retrieved and ultimately used to help an advertiser understand their overall ROI.
- Advertisers using the Google content network often run Placement Performance reports to gain insight into how their ads are performing on specific sites.
By using the AdWords API to retrieve reports, you can easily save results to your own computers and not be limited by the maximum of fifteen reports you can store in AdWords MCC accounts at a time.
6) Insert ads before keywords
Optimize your campaigns by always inserting ads into an ad group before placing keywords in it. Unlike creating ad groups through adwords.google.com or AdWords Editor, if you insert keywords first when you create an ad group via AdWords API, AdWords' Quality Based Bidding will temporarily assign relatively high minimum cost-per-click values. This is a very common mistake, and one that can very easily be avoided. Take extra care to follow this tip to ensure optimal performance.
7) Create a local store of AdWords data
Enjoy the power of having AdWords data on a server in your office. Many users boost the efficiency of their AdWords API response times by mirroring important parts of their campaigns in a local database. Having a copy of the data allows you to rapidly query against it and retrieve information on your campaigns, ad groups, keywords, and more without having to wait for a SOAP request to travel across the internet and be processed and returned. This setup can also eliminate waste if you need to make redundant AdWords API requests.
One word of caution: it's crucial to keep your local data updated, otherwise it can quickly become stale. This is especially true since it's possible to update AdWords data via multiple channels (i.e., adwords.google.com, the AdWords Editor, the AdWords API, and even other systems), meaning you could fall out of sync if you’re not diligent.
8) Use the AdWords API libraries
Why reinvent the AdWords API wheel? We’ve created two resources to help jump-start your development.
- AdWords API Client Libraries: Ease the process of writing code to access AdWords accounts.
- AdWords API Starter Kit: Focus on your business logic through the Starter Kit's high-level classes and functions that encapsulate the details of the AdWords API.
9) Optimize your account
Use the AdWords API to streamline the performance of your campaigns and eliminate waste.
- Use zero-impression reports to eliminate low-performing keywords, which will save API Units, and time spent managing inefficient keywords.
- Use the Keyword Estimator when deciding to add new keywords or delete non-performing ones.
- Add negative keywords to filter out unwanted traffic. To identify potential negatives, use the Report Service to find search queries that resulted in unwanted clicks on your ads. Then use the KeywordToolService to build up a set of related keywords.
10) Handle disapproved ads
Sometimes ads submitted to AdWords don't comply with our editorial or content guidelines, which are designed to create as user-friendly experience as possible. To handle any disapprovals smoothly and reduce overall ad downtime, design a process for handling disapproved ads.
- File ExemptionRequests when you anticipate a perceived ad policy violation.
- Use reports to determine which ads have been disapproved.
- If errors occur due to ad policy violations, keep an eye on the error response that comes back, in particular on the isExemptable field; this will tell you if it's possible to file an exemption request for that ad.
We'll be performing routine system maintenance on Saturday, July 12 from approximately 10:00am to 2:00pm PST. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Cheers,
-Jeffrey Posnick, AdWords API Team
Cheers,
-Jeffrey Posnick, AdWords API Team
As you could imagine, Google has a lot of historical data about keywords and the traffic they generate. Harnessing this data can give you a helpful starting point when you're trying to choose cost-per-click (CPC) bid ranges and keywords for a new product, for which you have no historical keyword or bid data in your own account.
AdWords API users can access our trove of historical keyword and bid data via the Traffic Estimator Service, which gives detailed estimates of how much traffic a keyword may generate at various CPC values. The service is not only useful for new products or campaigns, but it can also estimate the impact of changing the Max CPC of existing keywords as well.
Let's say you'd like estimates for keywords in a new campaign. Below are some tips on deciding whether estimateKeywordList() or estimateCampaignList() is right for you. These two methods are similar, but vary in how much control you have to configure campaign settings when requesting estimates.
Because there are only a few parameters to configure, estimateKeywordList() is the most straightforward method to use. To estimate the traffic for the keyword sample with Broad matching and a Max CPC of $1.00 (1,000,000 micros), you could use this SOAP body:
However, it's important to understand the assumptions that are factored into that estimate, because they might not match the settings you'd like for your campaign. This method assumes that the network targeting of the hypothetical campaign is GoogleSearch, which means ads run only on Google search result pages. (Read more information on network targeting here.) Also assumed in the keyword estimates are a language targeting of 'English' (language code en) and a location targeting of 'All Countries and Territories'.
The implicit Google search network and English language targeting mean that you'll often get much lower estimates from estimateKeywordList() than you would expect--and sometimes, especially for non-English keywords, you won't get any meaningful results at all.
If you expect your campaign to use different targeting options from those of estimateKeywordList()'s defaults, you might want to use the more flexible estimateCampaignList() method instead. To give a basic example, the following SOAP request is equivalent to the previous estimateKeywordList() request and should give identical results:
To expand on that basic example, let's say you're thinking of running a campaign that targets users in Mexico and Spain who speak Spanish. You'd like to run this campaign with both SearchNetwork and ContentNetwork targeting. A request that takes those constraints into account and provides an estimate for the Broad-matched keyword muestra with a Max CPC of 1,000,000 micros would look like the following:
The estimates this request returns will likely be different from the results of a generic estimateKeywordList() call, and they'll be more accurate for your given scenario.
Estimating keyword traffic and CPC bids isn't an exact science, but if you use the right method of the TrafficEstimatorService, you'll often get valuable information that can help you plan your new campaigns. And although using estimateCampaignList() requires a bit more configuration than the more straightforward estimateKeywordList(), the extra effort is a worthwhile trade-off for the increased flexibility and accuracy when working with campaigns that have non-default settings.
--Jeffrey Posnick, AdWords API Team
AdWords API users can access our trove of historical keyword and bid data via the Traffic Estimator Service, which gives detailed estimates of how much traffic a keyword may generate at various CPC values. The service is not only useful for new products or campaigns, but it can also estimate the impact of changing the Max CPC of existing keywords as well.
Let's say you'd like estimates for keywords in a new campaign. Below are some tips on deciding whether estimateKeywordList() or estimateCampaignList() is right for you. These two methods are similar, but vary in how much control you have to configure campaign settings when requesting estimates.
Method 1: estimateKeywordList()
<estimateKeywordList>
<keywordRequests>
<maxCpc>1000000</maxCpc>
<text>sample</text>
<type>Broad</type>
</keywordRequests>
</estimateKeywordList>
<keywordRequests>
<maxCpc>1000000</maxCpc>
<text>sample</text>
<type>Broad</type>
</keywordRequests>
</estimateKeywordList>
However, it's important to understand the assumptions that are factored into that estimate, because they might not match the settings you'd like for your campaign. This method assumes that the network targeting of the hypothetical campaign is GoogleSearch, which means ads run only on Google search result pages. (Read more information on network targeting here.) Also assumed in the keyword estimates are a language targeting of 'English' (language code en) and a location targeting of 'All Countries and Territories'.
The implicit Google search network and English language targeting mean that you'll often get much lower estimates from estimateKeywordList() than you would expect--and sometimes, especially for non-English keywords, you won't get any meaningful results at all.
Method 2: estimateCampaignList()
<estimateCampaignList>
<campaignRequests>
<adGroupRequests>
<keywordRequests>
<text>sample</text>
<type>Broad</type>
</keywordRequests>
<maxCpc>1000000</maxCpc>
</adGroupRequests>
<networkTargeting>
<networkTypes>GoogleSearch</networkTypes>
</networkTargeting>
<languageTargeting>en</languageTargeting>
<geoTargeting>
<targetAll>true</targetAll>
</geoTargeting>
</campaignRequests>
</estimateCampaignList>
<campaignRequests>
<adGroupRequests>
<keywordRequests>
<text>sample</text>
<type>Broad</type>
</keywordRequests>
<maxCpc>1000000</maxCpc>
</adGroupRequests>
<networkTargeting>
<networkTypes>GoogleSearch</networkTypes>
</networkTargeting>
<languageTargeting>en</languageTargeting>
<geoTargeting>
<targetAll>true</targetAll>
</geoTargeting>
</campaignRequests>
</estimateCampaignList>
To expand on that basic example, let's say you're thinking of running a campaign that targets users in Mexico and Spain who speak Spanish. You'd like to run this campaign with both SearchNetwork and ContentNetwork targeting. A request that takes those constraints into account and provides an estimate for the Broad-matched keyword muestra with a Max CPC of 1,000,000 micros would look like the following:
<estimateCampaignList>
<campaignRequests>
<adGroupRequests>
<keywordRequests>
<text>muestra</text>
<type>Broad</type>
</keywordRequests>
<maxCpc>1000000</maxCpc>
</adGroupRequests>
<networkTargeting>
<networkTypes>SearchNetwork</networkTypes>
<networkTypes>ContentNetwork</networkTypes>
</networkTargeting>
<languageTargeting>es</languageTargeting>
<geoTargeting>
<countryTargets>
<countries>MX</countries>
<countries>ES</countries>
</countryTargets>
</geoTargeting>
</campaignRequests>
</estimateCampaignList>
<campaignRequests>
<adGroupRequests>
<keywordRequests>
<text>muestra</text>
<type>Broad</type>
</keywordRequests>
<maxCpc>1000000</maxCpc>
</adGroupRequests>
<networkTargeting>
<networkTypes>SearchNetwork</networkTypes>
<networkTypes>ContentNetwork</networkTypes>
</networkTargeting>
<languageTargeting>es</languageTargeting>
<geoTargeting>
<countryTargets>
<countries>MX</countries>
<countries>ES</countries>
</countryTargets>
</geoTargeting>
</campaignRequests>
</estimateCampaignList>
The estimates this request returns will likely be different from the results of a generic estimateKeywordList() call, and they'll be more accurate for your given scenario.
Estimating keyword traffic and CPC bids isn't an exact science, but if you use the right method of the TrafficEstimatorService, you'll often get valuable information that can help you plan your new campaigns. And although using estimateCampaignList() requires a bit more configuration than the more straightforward estimateKeywordList(), the extra effort is a worthwhile trade-off for the increased flexibility and accuracy when working with campaigns that have non-default settings.
--Jeffrey Posnick, AdWords API Team