AdWords API Blog

AdWords Downtime: July 11, 10am-2pm PDT

2009-07-07T13:40:00.001-07:00

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

AdWords API v2009 Launch

2009-06-30T06:30:00.000-07:00

Hello all,

The AdWords API team is pleased to announce the launch of AdWords API v2009 in production! v2009 offers more speed, scale, and flexibility to developers, at a lower cost.

Back in April, we released a sandbox for our newest version of the AdWords API so you could begin experimenting. As mentioned in that blog post, we're using a new version naming convention to highlight the significant differences between this version, called AdWords API v2009, and v13.

This launch is a production beta, and we're asking developers to sign up for access here. We'll add you to our whitelist on a rolling basis,and send each of you a confirmation email once you've been added.

We've made a few policy changes in the API v2009 as well:

Revised Terms and Conditions - We've updated our Terms and Conditions to improve clarity. This change includes a more comprehensive explanation of our policy regarding the commingling of data, and also redefines the required minimum AdWords functionality for third party developers. You can see the list of required and optional features here.
Lower costs - v2009 comes with a new Rate Sheet that reflects the improved efficiency of the new system. We've lowered the cost of v2009 for the average developer by approximately 20% through reducing the unit cost of our most commonly called operations -- add criteria, add add, and set adgroup.

Getting started with v2009:

Once you've applied for access, you can find comprehensive developer documentation on our v2009 homepage.

While you're waiting for access to the v2009 beta, we encourage you to begin experimenting immediately with the v2009 sandbox. The sandbox doesn't charge for quota, and all you need to access it is your current Google account username and password. Please remember that the sandbox is a testing and development environment, so changes made there won't affect your live AdWords account. You can read more about sandbox best practices here.

What to expect next:

Over the next few months, we'll continue to introduce new features and additional AdWords functionality. Prior to moving added features to production, they'll be released to the v2009 sandbox so that you can try them out in advance. As they become available, we'll announce them on our blog. Some of the most notable are:

Partial failure acceptance - We plan to support partial failures, which means that large posts won't be completely rolled back due to a few small errors. This allows you to keep moving forward with development without halting to re-do posts.
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.)

Keyword Tools - With new keyword management tools, you'll be able to directly access new URL-specific keyword suggestions from the AdWords Keyword Tool and the Search-based Keyword Tool through the API.
MCC and Reporting functionality.

While we continue to roll out these offerings, both AdWords API v13 and v2009 will be fully supported. We'll begin the sunset countdown for v13 once we remove the v2009 whitelist and all developer have acquired access. Because we're introducing more changes than usual with this version, we'll extend the normal sunset period for v13, so it won't sunset until early 2010. By signing up for the v2009 whitelist now, you have the opportunity to get a head start on development.

Best,

Doug Raymond

Product Manager, AdWords API

AdWords API v2009 Sandbox Update

2009-06-23T11:56:00.000-07:00

We are making major updates to the v2009 Sandbox environment starting today and continuing throughout the week. Because of these changes, the v200902 Sandbox environment will be unavailable. We will post more information about what's new in the v2009 Sandbox environment once the work is complete--please stay tuned, and apologies for the downtime.

The v13 Sandbox environment should remain functional throughout this process.

-The AdWords API Team

AdWords Downtime: June 13, 10am-2pm PDT

2009-06-10T09:28:00.001-07:00

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

Client Library Updates: Part 2

2009-06-10T07:55:00.000-07:00

Last month we announced an update of our client libraries to improve their feature sets and make them more consistent across the various programming languages we support. This coincided with the release of the v2009 Sandbox, and a lot of those changes were meant to ensure that the client libraries were still just as easy to use, but also supported the newly-released v200902 API version.

We've continued our work on the client libraries and are now making more features available:

Utility methods that make use of the API to retrieve a breakdown of API usage per method or per client.
The ability to retrieve report data in CSV format.
Utility methods for retrieving several types of codes used with the API (cities, metros, timezones, etc.).
Full NDoc/JavaDoc/RDoc/Epydoc/perldoc documentation for the client library code.
Unit tests for the core library functionality and utility modules.
Finer-grained handling of API exceptions.
Improved runtime validation on the client side.

Some of these features are already present in a few client libraries, but we're now making them all available across Java, .NET, Python, Ruby and, where applicable, our newly released Perl libraries (which only support v200902).

You can find all the client libraries at the usual place: http://code.google.com/apis/adwords/docs/clients.html. Don't miss out on all the cool new stuff!

-- Sérgio Gomes, AdWords API Team

We Tweet

2009-05-21T13:51:00.000-07:00

For those who consider blogs or discussion groups passé, we wanted to let you know that you can now stay up to date on the latest AdWords API announcements by following @adwordsapi on Twitter.

AdWords API on App Engine (Python)

2009-05-19T15:06:00.000-07:00

Most of you have probably heard about Google App Engine, which lets you write web applications that run on Google's infrastructure. But did you know that the code which you develop using the AdWords API can be easily hosted on App Engine, thus making it many times easier to build, maintain, and scale your application as your traffic grows?

Today, we'd like to release a demo application that can be hosted on App Engine and is uses the AdWords API to communicate with the Sandbox environment (it is just as easy to access production AdWords accounts). In this demo, we access a given Sandbox account using the AdWords API and illustrate the following operations and features:

Retrieve existing campaigns.
Retrieve stats for each campaign.
Add new campaigns.
Update a campaign's budget.
Retrieve existing ad groups.
Add new ad groups.
Keep track of API usage for each user in a datastore.

We hope this demo will start you off in creating innovative and cool applications that take advantage of the AdWords API's ease of use and Google's infrastructure.

-- Stan Grinberg, AdWords API Team

Client Library Updates: Part 1

2009-05-14T12:43:00.000-07:00

There are a lot of changes going on with the AdWords API lately and we'd like to take a minute to talk about what else we have in store. In recent news, we released the API v2009 Sandbox and we appreciate all the great feedback we are getting (keep it coming!). With the release the v200902 API, we also have begun updating the client libraries for each of the supported languages. The client libraries have always made it simple for both first time developers and experts to use our API and we are now adding even more features to improve your API experience.

Above all, we want to allow you to experiment with the API v2009 Sandbox while still being able to make production calls to the v13 version. To that extent, each client library now has cross-version compatibility so that v200902 code and v13 code can be run together. It still stands, though, that v200902 can only operate within the Sandbox. Included in each client library are some examples showing you how to use the v13 code along with v200902 to supplement your learning.

In addition to our existing list of supported client libraries, a new Perl client library, found here http://code.google.com/p/google-api-adwords-perl/, has been developed specifically for use with v200902. This library does not include support for the v13 services, but it does offer most of the functionality that our other client libraries offer.

The support for v200902 in the APIlity (PHP) client library is in the works as well.

Here's some other features that you'll find in the new refresh of each client library:

Improved logging support.
Reports can now be downloaded through the client library.
Full support for UTF-8 encoding.
Thread-safe architecture.

As always, you can find a list of supported client libraries here: http://code.google.com/apis/adwords/docs/clients.html

We'll be releasing more features as the client library update continues, so stay tuned!

-- Adam Rogal, AdWords API Team

AdWords Downtime: May 16, 10am-2pm PDT

2009-05-13T10:40:00.001-07:00

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

2009-05-07T12:53:00.000-07:00

We want to take a minute to notify all AdWords API developers about an upcoming change in the way bids are handled in campaigns that make use of the Budget Optimizer. If none of your campaigns use the Budget Optimizer, or if you never plan on turning the Budget Optimizer off, then feel free to stop reading (and get back to trying out the new v2009 Sandbox!).

Each Campaign object has a budgetOptimizerSettings property, which in turn has a takeOnOptimizedBids setting. Currently, if takeOnOptimizedBids is set to false and you turn off the Budget Optimizer in a campaign, the original bids that were manually set for the ad groups and criteria contained in the campaign will be restored. In other words, the AdWords API will save your old bids from before the Budget Optimizer was turned on, and restore them when it is turned off. If takeOnOptimizedBids is set to true, however, the old bids will not be restored when the Budget Optimizer is turned off. Instead, the last bids that were automatically set by the Budget Optimizer will persist for the ad groups and criteria in your campaign.

You can, if you wish, use the AdWords API to manually update the bids for ad groups and criteria once the Budget Optimizer is turned off in either scenario.

The upcoming change will effectively treat takeOnOptimizedBids as if it were set to true (regardless of what it is actually set to) for all campaigns using the Budget Optimizer. Once the Budget Optimizer is turned off, all bids will be set to the last bid used by the Budget Optimizer. This change will match the behavior currently in place when the Budget Optimizer is turned off via the AdWords web interface.

We're planning on making this change to AdWords API behavior on May 19. It is not likely that you will have to make any substantial changes to your code in advance of this change, but please take the new behavior into account when you write code that turns the Budget Optimizer off.

-Jeffrey Posnick, AdWords API Team

AdWords API v2009 Sandbox Launch

2009-04-28T16:25:00.000-07:00

Hello all,

As we mentioned in our December blog post "A preview of 2009 API changes," we've been hard at work on re-building the AdWords API to offer our developers improved speed, functionality, and flexibility.

Today, we're announcing the launch of the API 2009 sandbox, so you can begin experimenting with the latest version of the AdWords API. We're using a new version naming convention to highlight the significant differences between this version, called AdWords API v2009, and v13.

There are several key differences in how API v2009 works:

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.
Lower costs: We will 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 increasing
efficiency of quota use. The v2009 sandbox is free to use, and once
these services are in production, they will be tied to a new rate
sheet that lowers the average cost of an operation. The new rate sheet
will apply only to API v2009, and will be launched when v2009 goes
into production.

Most AdWords functionality is available in the core services we
exposed today:

AdGroupAdService
AdGroupCriterionService
AdGroupService
CampaignCriterionService
CampaignService
CampaignTargetService

Forthcoming features include:

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.

We'll release the remaining features needed for full AdWords parity in the coming months. Forthcoming features include: Reporting, Keyword tools, MCC functionality, and change history.

How to access the API v2009 Sandbox:
The API v2009 Sandbox does not charge for quota, and will accept your current Google account login. In addition, the backend database for the v2009 Sandbox is shared with the v13 Sandbox environment. This means that any existing campaigns, ad groups, ads, and keywords that
you created under your login email using the v13 Sandbox will exist in the v2009 Sandbox. Please remember that the sandbox is a testing and development environment. The changes made here will not impact your live AdWords account. You can read more about Sandbox best practices here: http://adwordsapi.blogspot.com/2009/03/adwords-api-sandbox-best-pract...

What comes next:
We plan to launch the core functionality of API v2009 on our production servers in about 2 months, with the remaining functionality needed for AdWords parity released over the following 3 months. During that time, both AdWords API v13 and v2009 will be fully supported. We'll begin the sunset period for v13 once we've reached feature parity in API v2009. Since we're introducing more changes than usual, we'll extend the normal 4-month sunset period for v13, so it won't sunset until sometime in early 2010.

Documentation for the API v2009 sandbox is available on our codesite at: http://code.google.com/apis/adwords/v2009/docs/

We hope you'll kick the tires of our new API and give us plenty of feedback. We've established a special email address for you to share your thoughts: adwordsapi-relaunch@google.com. We look forward to your comments, suggestions and questions.

Thank you,

Doug Raymond
Product Manager, AdWords API

AdWords Downtime: April 18, 10am-2pm PDT

2009-04-15T08:12:00.000-07:00

The system maintenance we had intended for last Saturday, April 11, did not take place. As a result, we have rescheduled it for this Saturday, April 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

Developer Docs: v13 in Chinese, Japanese, and now Korean (updated)

2009-04-13T15:02:00.000-07:00

When we first announced non-English translations of our AdWords API Developer's Guide, we provided Japanese and Chinese versions of the v12 documentation. Our team has been hard at work since then, and we're happy to announce that the existing Chinese and Japanese translations have been updated to cover v13 of the AdWords API. In addition, a Korean translation of the v13 documentation is now available.

Update: Developers who speak Spanish and Portuguese will be happy to know that we've released the v13 documentation in their languages as well.

We'll continue to release translations for additional languages in the future, so stay tuned for more updates!

--The AdWords API Team

AdWords Downtime: April 11, 10am-2pm PDT

2009-04-08T10:19:00.000-07:00

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

Ad Scheduling: it's all about timing

2009-04-02T07:49:00.000-07:00

"There's a time for everything." This is something I've been hearing since I was a kid, but today I'm not here to tell you that you shouldn't have your dessert before your meal or play with noisy toys after dark; rather, I'd like to talk to you about whether it's really a good idea to advertise your lunch menu or your toy shop discount when your customers are sleeping.

Advertising, as is the case with most things in life, is all about timing. A lot of businesses have special advertising needs during certain times of day, and they'd like their customers to know about them at the right time.

Let's take the example of a newly opened downtown coffee shop that's looking to let people know about its great selection by advertising with AdWords. What happens when their ad runs at night? Well, people will learn about the menu, but at the wrong time. Since it's now after hours, and the place is closed, they might forget about it overnight and not visit the coffee shop the next day; all of this simply because that was the wrong time to be seeing that ad. Another example would be a toy shop running a special "lunchtime craze" deal to try to increase sales during that time of day; advertising after the event is not very useful and may even be counter-productive, as it's disappointing for people to realize that the promotion hours are over.

Fortunately, there are mechanisms built into AdWords and the AdWords API to allow you to decide when to run your ads, automatically, without requiring you to manually enable and disable them; this is called "Ad Scheduling".

Scheduling works at the campaign level, so it applies to all active ad groups and ads inside it. The AdSchedule object contains two items:

an "intervals" list, containing any number of SchedulingInterval objects
a "status" field, that enables or disables the AdSchedule

Each SchedulingInterval not only allows you to define a number of properties, such as day and starting/ending times, but also, notably, a multiplier. This multiplier is a very useful tool, as it provides a way to enable and disable displaying of the ad (by setting to a non-zero and zero value, respectively), as well as a way to increase or decrease your bids at certain times.

In our coffee shop example, to make sure the ads run mostly during opening hours, we would set displaying of ads to start a bit before opening and to end a little bit before closing:

SchedulingInterval[] days = new SchedulingInterval[6];

days[0].setDay(DayOfWeek.Monday);
days[1].setDay(DayOfWeek.Tuesday);
days[2].setDay(DayOfWeek.Wednesday);
days[3].setDay(DayOfWeek.Thursday);
days[4].setDay(DayOfWeek.Friday);
days[5].setDay(DayOfWeek.Saturday);

// Set weekday and Saturday schedule
for (int i = 0; i < 6; i++) {
// Start at 8:45 am...
days[i].setStartHour(8);
days[i].setStartMinute(45);
// ... and end at 7:45 pm
days[i].setEndHour(19);
days[i].setEndMinute(45);
// Run at normal bid rates
days[i].setMultiplier(1.0);
}

// Closed on Sunday, so we're omitting it from the array

As for our toy shop, in order to give customers fair warning about the special lunchtime deal, advertising would start early in the morning and increase significantly during the promotion hours:

SchedulingInterval early = new SchedulingInterval();
SchedulingInterval peak = new SchedulingInterval();

// Sample schedule for Monday
early.setDay(DayOfWeek.Monday);
peak.setDay(DayOfWeek.Monday);

// Start at 8:00 am...
early.setStartHour(8);
early.setStartMinute(0);
// ... and run until promotion starts
early.setEndHour(12);
early.setEndMinute(0);
// Run at normal bid rates
early.setMultiplier(1.0);

// Start higher bidding at noon...
peak.setStartHour(12);
peak.setStartMinute(0);
// ... and run until promotion ends...
peak.setEndHour(14);
peak.setEndMinute(0);
// ... at double the bid!
peak.setMultiplier(2.0);

(And here's how you can add a campaign with scheduling in your language of choice)

With these small changes to your campaigns, you should be able to make the most out of your ads by having them show at the right time. That likely means better, more focused targeting, with higher returns, all for just a little bit of setup work; that's like eating your cake and keeping it too! Just make sure you don't do it before lunch, otherwise it'll spoil your appetite.

--Sérgio Gomes, AdWords API Team

Better know a service: InfoService

2009-03-27T14:40:00.000-07:00

We, at the AdWords API Team, are often asked questions such as "Where have all my units gone?" and "How many API units has a particular account used in the last month?" Luckily, we have supplied you with a great set of tools with InfoService to answer these questions. In this blog post, we'll talk about some basic uses of this service, as well as some caveats that can be solved using some more advanced techniques. All code examples have been coded using the AdWords Java Client Library.

Update: both of these examples have now been included as utility methods in the file UnitsUtils.java. The example links below have been updated as well.

Where have all my units gone?

"Where have all my units gone?" is one of the most frequent questions asked by our developers seeking to trim down their API usage. Although InfoService provides the method getUnitCountForMethod, it is not inherently obvious how to generate a full mapping of usage. The heart of the problem is that, to call getUnitCountForMethod, you must pass it a service name and method. To get a full mapping of method to usage, getUnitCountForMethod must be called for each service and method pair. In the method UnitUtils.getMethodUsage, I have shown how you might do this.

The method is broken into two parts: populating a full mapping of service name to list of method names, and calling getUnitCountForMethod for each mapping. The result of each call is then put into a new map, referred to as methodUsage in the method. When the method has finished running, which may take a few seconds, methodUsage will have a mapping of serviceName.methodName to quotaUsage and the output will resemble:

AccountService.getAccountInfo = 3
AccountService.getClientAccountInfos = 257
AccountService.getClientAccounts = 0
AccountService.getMccAlerts = 0
AccountService.updateAccountInfo = 0
...
AdService.addAds = 5005
AdService.checkAds = 0
AdService.findBusinesses = 0
AdService.getActiveAds = 0
AdService.getAd = 0
AdService.getAdStats = 0
AdService.getAllAds = 0
AdService.getMyBusinesses = 0
AdService.getMyVideos = 0
AdService.updateAds = 0
...
TrafficEstimatorService.checkKeywordTraffic = 0
TrafficEstimatorService.estimateAdGroupList = 0
TrafficEstimatorService.estimateCampaignList = 0
TrafficEstimatorService.estimateKeywordList = 0

As you can see, many of my units went towards adding Ads. Using this data, I could enter my monthly values into a spreadsheet and plot my usage over several months. Not only could I easily spot where all of my units have gone, but I would also be able to spot any out of the ordinary behavior as well.

As a side note, regardless of the credentials supplied to the service, this method will only gather data against the developer token. Meaning that, supplying a clientEmail or clientCustomerId will not give a finer grained set of results.

How many API units has a particular child account used in the last month?

Another great feature of InfoService is that it allows you to determine how many units a particular child account has used over a period of time. This information can be used to invoice clients, if you are developing for an Agency, or to perform cost/ctr analysis, if you wished to optimize your accounts per API spend.

There is one caveat, however. Let's say that we have an account structure that resembles the one below:

We have a top most MCC, Top-MCC, which is the root of our tree. Since our goal is to generate a mapping of child account to the amount of quota used, a first approach may be to run getUnitCountForClients for each client, as shown below:

InfoService.getUnitCountForClients(["Sub-MCC-1",

"Sub-MCC-2", "Client-1", "Client-2",

"Client-3", "Client-4"],

"3/1/2009", "3/31/2009");

From the results, you can create a mapping that resembles:

Sub-MCC-1 = 55
Sub-MCC-2 = 70
Client-1 = 500
Client-2 = 650
Client-3 = 600
Client-4 = 400

You'll notice that while this data gives you some idea of client usage, there's no aggregation of client usage up to the MCC; Sub-MCC-1 returns just the number of units called directly on that account, such as from a command with headers:

<email>Top-MCC</email>
<password>passwordForTop-MCC</password>
<developerToken>...</developerToken>
<applicationToken>...</applicationToken>
<userAgent>...</userAgent>
<clientEmail>Sub-MCC-1</clientEmail>

What you may actually want is an aggregation of unit usage such as:

Top-MCC = 2275
Sub-MCC-1 = 1305
Sub-MCC-2 = 470
Client-1 = 500
Client-2 = 650
Client-3 = 600
Client-4 = 400

In the method UnitUtils.getClientUnitsUsage, I show how to traverse the full account tree below the top most MCC and sum the units for each client to produce a mapping like the one above. However, if by some chance, a client has two parent accounts, linked through UI/API and API, and those parents are both distant children of the same parent, that client will be doubly counted. We've also shown how to keep track of these doubly counted clients in the demo.

We hope that these new utility methods will help you keep track of your API usage and stay tuned for more great demos like these!

--Adam Rogal, AdWords API Team

AdWords API sandbox - Best practices

2009-03-20T10:42:00.000-07:00

The API sandbox is open to anyone who wants to test code during development, and it's completely free. We recommend using the sandbox as much as possible to catch your bugs during development so they won't hit your production account later. Here are some tips on using the sandbox effectively:

Initialize your sandbox account

Make sure that the first call to the sandbox is a get() call from AccountService, preferably AccountService's getClientAccounts(). Assuming you use user@domain.com as the login email, this call will initialize the sandbox and create 5 test client accounts, namely client_1+user@domain.com to client_5+user@domain.com for your sandbox account. While making this call you should not provide the clientEmail or clientCustomerId headers, since this call expects an MCC account to succeed.

While making a getClientAccounts() call to the sandbox, set the SOAP headers as follows:

email: address of any google account, such as a Gmail account
password: password of the account
useragent: set to any identifying string
developerToken: set to the value for email, with the string '++USD' (or the currency code of your choice) appended
applicationToken: ignored, and could be set to anything or left out
clientEmail: should be either set to the empty string or left out

clientCustomerId: should be either set to the empty string or left out

The sandbox database is usually refreshed once every month, wiping out all client accounts. Making getClientAccounts() as your application's first API call ensures that all your calls happen against a properly initialized sandbox account.

Simulate error responses

Because a good application needs to gracefully handle errors thrown by the AdWords API, the sandbox provides a mechanism for simulating error messages. If you use user@domain.com++errorCode as the email for a call to the sandbox, the sandbox will return an error response with error code set as the desired errorCode, and a text message indicating that an error response has been forced by the sandbox.

The error code should be set to one of the valid error codes. For instance, by providing login email as user@domain.com++17, I can simulate error code 17 (account exceeded maximum number of allowed campaigns).

The SOAP response looks as follows:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Server.userException</faultcode>
      <faultstring>Error forced by the request (Sandbox)</faultstring>
      <detail>
        <ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v13">
          <ns1:code>17</ns1:code>
          <ns1:message>Error forced by the request (Sandbox)</ns1:message>
          <ns1:trigger>user@domain.com++17</ns1:trigger>
        </ns1:fault>
      </detail>
    </soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>

Similarly, you can also test for some policy violations in ads and keywords. For instance, providing repeated punctuation in the ad or keyword text, such as "Hello World!!" as the ad title, should trigger a policy violation error. However, the sandbox doesn't have all of the policy checks in place, so you can't test your application against every possible policy violation, e.g. trademark-related violations.

Generate reports

Since generating reports is one of the most common calls in the AdWords API, the sandbox provides features to test each stage of your report generation logic. In the sandbox, you can create either a report whose status does not change, or a report whose status changes from pending to deleted. If you include any one of the following strings in the report name field while creating it, it will create a report with the specified status.

fixstatus=Pending
fixstatus=InProgress
fixstatus=Completed
fixstatus=Failed

If the name doesn't contain any of the above codes, the sandbox will create a report whose status changes as follows:

During the first minute since the report job was scheduled, the status is Pending.
During the second minute, the status is InProgress.
During the third minute, the status is Completed.
After the third minute, the report is deleted.

Also, a call to getAllJobs will return four reports, one for each value of ReportJobStatus. Sandbox reports do not return any data related to any live accounts. So if you want to test your report parsing logic against some live data, you can generate a report of the desired type in the Reports Center of your production account, download it in xml format, and use it to develop and test your code.

Handling account limits

As with a live account, an AdWords sandbox account can hold a maximum of 25 active campaigns, with up to 100 active ad groups per campaign. If your program runs into these limits, then you can change the status of some campaigns or ad groups to "deleted."

TrafficEstimatorService and KeywordToolService behavior

Both TrafficEstimatorService and KeywordToolService are available for use in AdWords API sandbox. However, both these services return fake data. TrafficEstimatorService will give you fake data for Position, CPC, and Clicks per day. KeywordToolService can give you fake Seed-based keyword suggestions when using getKeywordVariations. It can also give you content-based keyword suggestions and SiteKeyword statistics when using getKeywordsFromSite.

The AdWords API sandbox can greatly help you with your development by preventing bugs from hitting production account during early stages of development. You can find more information on AdWords API sandbox at http://code.google.com/apis/adwords/docs/developer/adwords_api_sandbox.html.

-Anash P. Oommen, AdWords API Team

AdWords Downtime: March 14, 10am-2pm PDT

2009-03-10T14:39:00.000-07:00

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

AdWords API Developer Docs: Now in Chinese and Japanese!

2009-02-17T11:23:00.000-08:00

It's easy to write code using the AdWords API in the programming language of your choice, thanks to all of our client libraries. But when it comes to written language, you're more constrained--our recent developer documentation has only been maintained in English.

We're happy to announce that this is no longer the case, and our Developer's Guide now features a Chinese and Japanese translation. If you're not automatically redirected to the appropriate language when you visit that page, use the popup menu in the upper right hand corner of the web page to switch to one of the supported languages.

Please note that only the v12 version of the Developer's Guide has been translated. We're working hard to get v13 translated as well, and hope that the v12 documentation proves useful for v13 developers--the majority of the documentation is the same between the two versions. We will be leaving the v12 documentation up on the site for an extended period of time.

We'll be releasing translations for additional languages in the future, so stay tuned for more updates!

--The AdWords API Team

AdWords Downtime: February 21, 10am-2pm PST

2009-02-17T11:17:00.001-08:00

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

Sunsetting v12 on February 23, 2009

2009-02-04T10:10:00.001-08:00

In accordance with our policy of sunsetting older versions of the AdWords API, we will turn off access to version 12 of the API on Monday, February 23, 2009. Version 13 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 official Google client libraries all support version 13 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 12 to 13.

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.

-- AdWords API Team

Keyword Match Type and the KeywordToolService

2009-01-20T14:20:00.000-08:00

We first blogged about AdWords API v13's new keyword search volume info functionality back in November, and it remains a popular topic among developers. We've heard a number of follow-up questions about how the results from v13's KeywordToolService match up with the results available via the corresponding web application, especially when it comes to issues regarding keyword match type. There are two different scenarios in which you might want to specify match type when retrieving keyword variations, and hopefully the information in this blog post will clear up some confusion as to how the KeywordToolService supports that functionality.

One scenario involves giving a hint to the keyword variation service as to what kind of query you want to use as the seed. If you're calling getKeywordVariations(), you use the type attribute of the SeedKeyword object to do this. So, for example, if you want to generate variations based on a phrase match for "baseball bat", you'd specify "Phrase" for the type attribute and "baseball bat" for the text attribute of the SeedKeyword. If instead of a phrase match you were interested in generating keyword variations based on a broad match, you'd instead specify "Broad" for the type attribute. The important thing here is that the type attribute can affect the specific variations that are returned. In the "baseball bat" example, most of the variation keywords that are returned are the same for the two match types, but there are some differences. For example, the variation "baseball training bat" is only returned when you specify a Broad match type.

The options outlined above directly translate into using the web version of the tool and specifying two different match types for the source keyword. In the section in which you're instructed to "Enter one keyword or phrase per line", if you were to enter the literal text "baseball bat" (with quotes) you'd specify a Phrase match type. If you entered baseball bat (without quotes) you'd specify a Broad match type. (An Exact match type is expressed as [baseball bat], i.e. with brackets around the text.)

This distinction only applies to the getKeywordVariations() method of the KeywordToolService. getKeywordsFromSite() doesn't allow you to specify a match type for the source keyword because there is no source keyword; instead, you're passing in a specific URL to use as the source, and a match type would not make sense in that context.

The second scenario in which you might care about match type involves the search volume results for each SiteKeyword or KeywordVariation object that is returned from getKeywordsFromSite() and getKeywordVariations(). The web version of the tool provides a popup menu in the results area allowing you to select the match type you're interested in. When you choose a match type, it will update the search volume information of each suggested keyword accordingly. Unfortunately, there is currently no way to retrieve search volumes for different match types using the API's KeywordToolService methods. The search volumes in the results returned from the API should roughly correspond to what you'd see with the Broad setting for match type in the web tool, but retrieving search volumes for Phrase or Exact match types is not possible.

--Jeffrey Posnick, AdWords API Team

AdWords Downtime: January 10, 10am-2pm PST

2009-01-06T11:04:00.000-08:00

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

A preview of 2009 AdWords API changes

2008-12-11T15:18:00.000-08:00

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:

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

AdWords API Hostnames

2008-12-10T14:22:00.000-08:00

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.

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.