Today, we announced the launch of Google Instant, a new Google.com interface that shows relevant results while the user types. To read more about how this change affects AdWords advertisers, please visit the Inside AdWords Blog.
With this change, you might notice some fluctuations in impression volume. For example, you may find that certain keywords receive significantly more or less impressions moving forward. Despite any change in impressions, Google Instant is intended to increase the quality of the clicks on your ads and therefore boost your overall campaign performance.
For more information about Google Instant, visit our Help Center.
-- Posted by Jason Shafton, Product Marketing Manager
One of the most critical and complicated aspects of using an API is error handling. To help address this, we’ve included detailed information about each type of error in the reference documentation and posted articles discussing general error handling best practices. While these resources are great at helping to determine what the an error is, we’ve heard from you on the forum that they often don’t provide enough context as to why the error occurred and what you can do to prevent it in the future.
With this in mind, we’ve put together a new troubleshooting guide for the most common errors in the AdWords API. Each error includes a brief summary of what went wrong, some common causes, a recommended tip for handling the error when it occurs, and steps you can take to prevent the error from occurring.
We hope that this guide will be your first stop when you get an error you haven’t encountered before. We’ll continue to update it based on community feedback and the errors you run into most often. If after reviewing these resources you still have questions, please post them to the forum.
Best,
- Eric Koleda, AdWords API Team
Have you ever wondered how your keywords could have performed with a different bid? The bid simulator feature released last year allows you to do just that. Using data from the last seven days, it calculates the impressions, clicks, and cost your keywords could have received if different maximum CPC bids were used. This information was previously only exposed in the AdWords web interface, but is now available in the v201003 version of the API with the BidLandscapeService.
The getBidLandscape() method is used to retrieve the bid simulation results, also known as bid landscapes. You can use the selector to filter the results by campaign, ad group, or keyword ID. For example, to retrieve the results for a single keyword using the PHP client library you would use the following code:
// Create selector.
$selector = new CriterionBidLandscapeSelector();
// Create id filter.
$idFilter = new BidLandscapeIdFilter();
$idFilter->adGroupId = $adGroupId;
$idFilter->criterionId= $keywordId;
$selector->idFilters = array($idFilter);
// Get bid landscape for keyword.
$bidLandscapes = $bidLandscapeService->getBidLandscape($selector);BidLandscape contains a series of LandscapePoints, each of which represents a single simulation for that keyword. It isn’t possible to configure which bids are used in the simulations, but the points are chosen automatically by the system to give an interesting range of data. Each landscape point contains the impressions, clicks, and cost that the keyword could have received at that bid. In addition, it contains the field marginalCpc, which contains the incremental cost-per-click (ICC) at the simulated bid. More information on ICC values and how you can use them is outlined in a video by Google's Chief Economist, Hal Varian. Please note that depending on the recent performance of the keyword, only some of this information may be populated in the landscape point.ManualCPC bidding and target the GOOGLE_SEARCH or SEARCH_NETWORK networks. Additional restrictions are listed in the AdWords Help Center. The bid simulations are performed automatically in regular intervals, and new keywords or those with no impressions in the last seven days won’t have any associated results. No errors will be thrown when this happens, but the response will not contain a BidLandscape for that keyword.Account structure report is one of the popular report formats in v13 of the AdWords API. This report allows you to download all the account attributes in a single report without performance details. A common use of account structure reports is to sync a local database against the AdWords server without using more expensive get() API calls.
Despite being a useful report format, account structure report is a specialized report format available only through the AdWords API. We designed the new API such that standard report formats can support your needs rather than creating additional specialized report types. Therefore, the new AdWords API doesn’t have a separate account structure report type, but you can use the existing report types supported by ReportDefinitionService to download the same data. This blog post discusses how this can be done, so that you can migrate your existing account structure reports to the v201003 version of the AdWords API. This blog post assumes you are familiar with the usage of ReportDefinitionService, if not, we suggest that you read our introductory blog post first.
Retrieving campaign structure information
You can download all campaigns in an account in the v201003 version of the AdWords API using CAMPAIGN_PERFORMANCE_REPORT. The xml request for adding the report definition is shown below:
<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003"> <operations> <operator>ADD</operator> <operand> <selector> <fields>Id</fields> <fields>Name</fields> <fields>Status</fields> <fields>Amount</fields> </selector> <reportName>Campaign performance report #1277301277814.61</reportName> <reportType>CAMPAIGN_PERFORMANCE_REPORT</reportType> <dateRangeType>TODAY</dateRangeType> <downloadFormat>XML</downloadFormat> </operand> </operations> </mutate>Retrieving the ad group structure information
<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003"> <operations> <operator>ADD</operator> <operand> <selector> <fields>Id</fields> <fields>Name</fields> <fields>Status</fields> <fields>CampaignId</fields> </selector> <reportName>AdGroup performance report #1277302184111.48</reportName> <reportType>ADGROUP_PERFORMANCE_REPORT</reportType> <dateRangeType>TODAY</dateRangeType> <downloadFormat>XML</downloadFormat> </operand> </operations> </mutate>
<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003"> <operations> <operator>ADD</operator> <operand> <selector> <fields>Id</fields> <fields>Headline</fields> <fields>Description1</fields> <fields>Description2</fields> <fields>DisplayUrl</fields> <fields>Url</fields> <fields>Status</fields> <fields>AdGroupId</fields> </selector> <reportName>Ad performance report #1277303749892.73</reportName> <reportType>AD_PERFORMANCE_REPORT</reportType> <dateRangeType>TODAY</dateRangeType> <downloadFormat>XML</downloadFormat> </operand> </operations> </mutate>If required, you can restrict the report to contain ads from only a particular ad group by setting a Predicate.
<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003"> <operations> <operator>ADD</operator> <operand> <selector> <fields>AdGroupId</fields> <fields>Id</fields> <fields>KeywordText</fields> <fields>KeywordMatchType</fields> <fields>IsNegative</fields> </selector> <reportName>Keyword performance report #1277353190509.28</reportName> <reportType>KEYWORDS_PERFORMANCE_REPORT</reportType> <dateRangeType>TODAY</dateRangeType> <downloadFormat>XML</downloadFormat> </operand> </operations> </mutate>
Reporting is an integral part of most AdWords API applications. To help you create and manage reports related to your AdWords campaigns, we introduced the ReportDefinitionService in the v201003 version of the AdWords API. In this post, we’ll cover the basics of working with the ReportDefinitionService. If you’ve used the v13 ReportService, you’ll notice that the new ReportDefinitionService differs in many ways from its v13 counterpart.
Retrieving the report fields
To create a report in the v201003 version of AdWords API, you pick a report type of your choice and then retrieve the list of supported fields using getReportFields. The Java code below shows how to retrieve the report fields:
// Get report fields.
ReportDefinitionField[] reportDefinitionFields =
reportDefinitionService.getReportFields(
ReportDefinitionReportType.KEYWORDS_PERFORMANCE_REPORT);
// Display report fields.
System.out.println("Available fields for report:");
for (ReportDefinitionField reportDefinitionField : reportDefinitionFields) {
System.out.print("\t" + reportDefinitionField.getFieldName() + "("
+ reportDefinitionField.getFieldType() + ")");
}
// Create ad group predicate.
Predicate adGroupPredicate = new Predicate();
adGroupPredicate.setField("AdGroupId");
adGroupPredicate.setOperator(PredicateOperator.EQUALS);
adGroupPredicate.setValues(new String[] {adGroupId});
// Create selector.
Selector selector = new Selector();
selector.setFields(new String[] {"AdGroupId", "Id", "KeywordText",
"KeywordMatchType", "Impressions", "Clicks", "Cost"});
selector.setPredicates(new Predicate[] {adGroupPredicate});
selector.setDateRange(new DateRange(startDate, endDate));
// Create report definition.
ReportDefinition reportDefinition = new ReportDefinition();
reportDefinition.setReportName("Keywords performance report”);
reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.CUSTOM_DATE);
reportDefinition.setReportType(ReportDefinitionReportType.KEYWORDS_PERFORMANCE_REPORT);
reportDefinition.setDownloadFormat(DownloadFormat.XML);
reportDefinition.setSelector(selector);
// Create operations.
ReportDefinitionOperation operation = new ReportDefinitionOperation();
operation.setOperand(reportDefinition);
operation.setOperator(Operator.ADD);
ReportDefinitionOperation[] operations = new ReportDefinitionOperation[]
{operation};
// Add report definition.
ReportDefinition[] result = reportDefinitionService.mutate(operations);
String url = "https://adwords.google.com/api/adwords/reportdownload?__rd="
+ reportDefinitionId;
HttpURLConnection urlConn =
(HttpURLConnection) new URL(url).openConnection();
urlConn.setRequestMethod ("GET");
urlConn.setRequestProperty("Authorization", "GoogleLogin auth="
+ user.getRegisteredAuthToken());
if (user.getClientCustomerId() != null) {
urlConn.setRequestProperty("clientCustomerId", user.getClientCustomerId());
} else if (user.getClientEmail() != null) {
urlConn.setRequestProperty("clientEmail", user.getClientEmail());
} else {
urlConn.setRequestProperty("clientEmail", user.getEmail());
}
urlConn.connect();
copyStream(urlConn.getInputStream(), new FileOutputStream(
new File(outputFileName)));
GET /api/adwords/reportdownload?__rd=XXXXXX HTTP/1.1 Host: adwords.google.com Accept: */* Authorization: GoogleLogin auth=XXXXXX clientEmail: XXXXXX
