AdWords API Blog

AdWords Downtime: August 23, 10am-4pm PDT

Tue, 19 Aug 2008 11:27:09 -0700

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

Sunsetting V11 on August 26th, 2008

Thu, 07 Aug 2008 10:06:58 -0700

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

AdWords Downtime: August 9, 10am-2pm PDT

Tue, 05 Aug 2008 13:08:14 -0700

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

Upcoming Reports Changes: August 19

Thu, 31 Jul 2008 15:05:51 -0700

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

Wed, 16 Jul 2008 10:47:18 -0700

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

Wed, 09 Jul 2008 09:46:32 -0700

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.

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

Tue, 08 Jul 2008 13:45:46 -0700

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

Wed, 02 Jul 2008 12:46:04 -0700

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

AdWords API Video Tutorial

Wed, 18 Jun 2008 13:14:46 -0700

The AdWords API team is pleased to announce a series of videos geared towards developers who are new to the AdWords API. These tutorials, and the companion website, http://awapiday.googlepages.com/, start with an overview of AdWords and the API, and then walk users through the steps involved in creating campaigns, ad groups, ads, and keywords from their own code.

The videos are broken down into nine parts:

A broad overview of AdWords and the AdWords API: http://youtube.com/watch?v=IvDd4CAn7s4
An introduction to the web material that will be used in the rest of the tutorial videos: http://youtube.com/watch?v=o25rdn3tVa0
Logging in to the AdWords API's Sandbox development environment: http://youtube.com/watch?v=6C0d3sGON40
Capturing debugging information useful when troubleshooting AdWords API behavior: http://youtube.com/watch?v=Kd50L1zK-GA
Creating campaigns using the AdWords API: http://youtube.com/watch?v=gmsR8PR2NUQ
Creating ad groups using the AdWords API: http://youtube.com/watch?v=t4LcZhFO4pA
Creating ads using the AdWords API: http://youtube.com/watch?v=_NpocMjDy4Y
Creating keyword criteria with the AdWords API: http://youtube.com/watch?v=dBubzgfv2dk
A discussion of resources for AdWords API information beyond what's available in the video series: http://youtube.com/watch?v=HFaKnZTAozA

A master playlist with all the videos is available at http://www.youtube.com/view_play_list?p=9CA736F591727260

All the videos have corresponding high quality versions, so be sure to click on the "watch in high quality" link on the YouTube page.

We hope that these resources are useful to you. As always, please feel free to post your comments to our forum if you have any questions.

Cheers!
Jeffrey Posnick, AdWords API Team

AdWords Downtime: June 21, 10am-3pm PST

Mon, 16 Jun 2008 16:14:06 -0700

We'll be performing routine system maintenance on Saturday, June 21 from approximately 10:00am to 3:00pm PST (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 Starter Kit Now Available

Tue, 03 Jun 2008 14:32:51 -0700

Learning a new API is sometimes difficult, and writing an application can be a lengthy process. To make things easier, we've developed the AdWords API Starter Kit. This collection of high-level functions and classes speeds up application development by providing:

A flexible and modifiable codebase that can be used as a base for a range of AdWords applications
A functioning demo that generates and adds campaigns, ad groups, ads, and keywords based on a set of products you define

By taking advantage of the AdWords API Starter Kit framework, developers can begin using the AdWords API faster, and focus more on creating customized ways to manage AdWords campaigns.

For more information on the AdWords API Starter Kit:

Visit the project home page
Read the AdWords API Starter Kit README

-- David Aubespin, Customer Solutions Engineer

AdWords Downtime: June 7, 10am-2pm PST

Mon, 02 Jun 2008 16:15:03 -0700

We'll be performing routine system maintenance on Saturday, June 7 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

Heading to the Google I/O Developer Event

Fri, 23 May 2008 13:12:00 -0700

Next week, on May 28th and 29th, we're headed to Google I/O. This will be Google's largest developer event of the year. There will be over 80 breakout sessions on the latest web development technologies as well as hands-on Code Labs and informal Q&A at Fireside Chats. You can see the complete session schedule on the event website. We'll be hosting a demonstration booth and answering questions about the AdWords API.

Hope to see you there!

-- Debbie Leight, Product Marketing

Integration of Code Samples into the Developer Guide

Thu, 22 May 2008 09:11:52 -0700

While referencing our online API documentation, you've probably found yourself switching between the developer guide and applicable code samples. We realized that it would be more helpful to you to find these materials in the same place. Therefore, today, we are happy to announce the integration of code samples directly into the developer guide. In the guide, for methods that have corresponding code samples, we've added a new "Samples" section. When you expand the plus box next to these sections, you will see:

examples of a method's usage in multiple (programming) languages,
syntax highlighting and line numbers,
easy navigation, and
a link to a full sample.

The AdWords API Developer's Guide is located at http://www.google.com/apis/adwords/developer/index.html. An example
of a method that lists a "Samples" section is at
http://www.google.com/apis/adwords/developer/AccountService.html#getAccountInfo.

Check it out and tell us what you think!

-- Stan Grinberg, Developer Programs Engineer

AdWords Downtime: May 17, 10am-2pm PST

Tue, 13 May 2008 13:10:20 -0700

We'll be performing routine system maintenance on Saturday, May 17 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

April API rate sheet reductions, we're not joking :)

Wed, 16 Apr 2008 17:13:42 -0700

In the past, we've been known for some creative April announcements. Today, however, I'm happy to report a few real reductions in API rates that will bring a smile to your face. You'll be glad to know we aren't joking.

We have made some enhancements to our system that have enabled us to drive greater efficiencies that are now reflected in savings to our API users.

Effective today, we have lowered the number of API units charged for the following services:

Service Name, Former Rate (in API units), New Rate

addAds: 125 -> 50 per item
addCriteria: 25 -> 20 per item
updateCriteria: 10 -> 3 per item
getKeywordVariations: 25 -> 20
getKeywordsFromSite: 25 -> 20
estimateAdGroupList: 25 -> 20 per item
estimateCampaignList: 25 -> 20 per item
estimateKeywordList: 25 -> 20 per item
scheduleReportJob: 1000 -> 500

API units will continue to be charged at a cost of US$0.25 (or local currency equivalent) per thousand units consumed; but these per-service rate reductions will bring substantial savings.

And as always, we encourage developers to use list methods whenever possible (e.g. addCampaignList). They are the most efficient (and cost-effective) way to process large data sets.

- Debbie Leight, Product Marketing

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

Wed, 09 Apr 2008 08:54:32 -0700

We'll be performing routine system maintenance on Saturday, April 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

AdWords API Coming Out of Beta

Sat, 05 Apr 2008 20:48:15 -0700

Having spent the last few years refining our release versioning systems and policies, usage model, and data center systems, we feel it is time to officially remove the beta label from the AdWords API.

We'd like to thank those of you who have supported the API over the last several years, and especially to those intrepid souls who first joined the beta in early 2005. Since our initial beta launch, the API has grown to support thousands of independent developers. The AdWords API is an integral part of the AdWords platform, and one we will continue to refine and develop in the years to come.

-- Borana Toska, Product Marketing

AdWords API Version 12 Now Available

Wed, 26 Mar 2008 08:47:30 -0700

We are happy to announce the release of the AdWords API Version 12 (V12).

V12 introduces several changes to the AdWords API. Below, you'll find the main highlights from this release. For a complete list of V12 changes, please see our release notes.

V12 HIGHLIGHTS

Conversion Optimizer support: Now you can enable Conversion Optimizer to pay only when an ad click leads to a conversion to adjust cost-per-acquisition bids through the AdWords API . Using Conversion Optimizer requires conversion tracking to be enabled on an existing campaign with at least 200 conversions in the past 30 days.

CPC bidding for placement-targeted ads: Now you can use Website.maxCpc or
AdGroup.siteMaxCpc to pay only when a user clicks on your placement-targeted ad.

Expanded code sample library: As mentioned in a previous blog post, we have released 140 new code samples, 20 in 7 programming languages. Check out it out at http://www.google.com/apis/adwords/samplecode.html

V11 SUNSET IN 2008

Per our versioning policy, V11 will be supported for four months from today, after which time it will be turned off. Therefore, please make sure that you upgrade to V12 before July 26, 2008. 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.

UPDATE: April 2, 2008

Please note that now you can enable Conversion Optimizer to adjust cost-per-acquisition bids through the AdWords API. The way this feature was initially described was inaccurate. We apologize for the confusion.

-- Borana Toska, Product Marketing

New Sample Code, and Lots of It!

Mon, 17 Mar 2008 12:44:40 -0700

Whether you're making your first API call or troubleshooting some crufty SOAP plumbing, we hope doing so is about to get a whole lot easier. Today, we're releasing 140 new code samples — 20 each in 7 (programming) languages. We redesigned the samples so they'd be:

simpler — every file has a discrete task and a minimum of external dependencies to better illustrate how it works,
more comprehensive — all the API's representative methods and most popular client languages are covered, and
more reliable — the code is normalized across languages for less expensive maintenance and updates.

Give them a try and tell us what you think!

You can download the latest sources from the AdWords API website.

— Brian Kennish, Developer Programs Engineer

AdWords Downtime: March 8, 10am-2pm PST

Tue, 04 Mar 2008 12:39:42 -0800

We'll be performing routine system maintenance on Saturday, March 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