Upcoming Reports Changes: August 19

Thursday, July 31, 2008


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.

  • 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.

AdWords Downtime: July 19, 10am-3pm PDT

Wednesday, July 16, 2008


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

AdWords API: Ten Best Practices

Wednesday, July 09, 2008


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.


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.

AdWords Downtime: July 12, 10am-2pm PST

Tuesday, July 08, 2008


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

Traffic Estimator Service Explained

Wednesday, July 02, 2008


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.

Method 1: estimateKeywordList()

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:

<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()

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:

<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>

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