AdWords API Blog

Discover v2009: Getting ideas with TargetingIdeaService

2009-11-03T14:46:00.000-08:00

As we announced recently, KeywordToolService and SiteSuggestionService were among the services deprecated to make way for their v2009 successors. In designing their new replacement, we sought to create a unified experience similar to our other v2009 services. The new TargetingIdeaService combines queries for both keywords and placements into one service with a common method to retrieve TargetingIdeas. In this blog post, we will discuss querying the new service for ideas to aid you in shaping your campaign and how you would go about migrating from v13.

Similar to our other new services, the TargetingIdeaService uses a get method along with a selector to query for both keywords and placements. There are currently two types of requests that can be made - ideas and stats. We will discuss querying for ideas here and save stats for a future blog post.

There are 4 main parameters of the selector which are used for querying ideas:

requestType - the request type equal to IDEAS or STATS.
ideaType - the type of idea to get equal to KEYWORD or PLACEMENT.
searchParameters - contains both the seed parameters as well as filters to apply to the results, which are specific to the ideaType.
requestedAttributeTypes - narrows the attributes returned to only those requested, which are specific to the searchParameters and ideaType.

Using these 4 parameters, you will have a vast degree of customization for your results. Each of these parameters and their limitations is best described in the TargetingIdeaSelector documentation page. We will now walk through a few examples on how you would replicate v13's functionality, and how you can improve upon it with v2009.

Replicating KeywordToolService.getKeywordVariations

In v13, you would typically retrieve a list of keyword variations from the getKeywordVariations method. Below is a snippet of code which replicates the basic functionality of this method.

Keyword keyword = new Keyword();

keyword.setText("cheap airline tickets");

keyword.setMatchType(KeywordMatchType.BROAD);

LanguageTarget language = new LanguageTarget();

language.setLanguageCode("en");

CountryTarget country = new CountryTarget();

country.setCountryCode("US");

TargetingIdeaSelector selector = new TargetingIdeaSelector();

selector.setRequestType(RequestType.IDEAS);

selector.setIdeaType(IdeaType.KEYWORD);

selector.setSearchParameters(new SearchParameter[] {

new RelatedToKeywordSearchParameter(null, new Keyword[] {keyword}),

new LanguageTargetSearchParameter(null, new LanguageTarget[] {language}),

new CountryTargetSearchParameter(null, new CountryTarget[] {country})});

selector.setPaging(new Paging(0, 6));

The results you get back may resemble keywords like:

cheap airline tickets/EXACT

cheap airline tickets/BROAD

cheap airline tickets/PHRASE

airline tickets/BROAD

airline tickets/EXACT

airline tickets/PHRASE

As you can see, since the results were not filtered, they weren't that great. You can improve the results by specifying additional search parameters in the selector:

// Using the same keyword from above, filter by removing the original

// keyword, by keeping the same match type, and by only choosing

// "long-tail" keywords.

new ExcludedKeywordSearchParameter(null, new Keyword[] {keyword}),

new KeywordMatchTypeSearchParameter(null,

new KeywordMatchType[] {keyword.getMatchType()}),

new CompetitionSearchParameter(null,

new CompetitionSearchParameterLevel[] {

CompetitionSearchParameterLevel.LOW}),

The results are now more interesting:

legion air tickets/BROAD

air tram tickets/BROAD

block air tickets/BROAD

sheap air tickets/BROAD

cheap airfare tracker/BROAD

cheap airfare forum/BROAD

You will notice now that the results are beginning to give you a better idea on how you would shape your campaign. We will now explore placement functionality, formerly found within the SiteSuggestionService.

Replicating SiteSuggestionService.getSitesByUrls

In v13, you would typically retrieve a list of similar websites to expand your content network campaign using the getSitesByUrls method. Below is a snippet of code which replicates the basic functionality of this method.

String[] urls = new String[] {"made-up-tickets-site.com",

"made-up-ticket-seller.com"};

LanguageTarget language = new LanguageTarget();

language.setLanguageCode("en");

CountryTarget country = new CountryTarget();

country.setCountryCode("US");

TargetingIdeaSelector selector = new TargetingIdeaSelector();

selector.setRequestType(RequestType.IDEAS);

selector.setIdeaType(IdeaType.PLACEMENT);

selector.setSearchParameters(new SearchParameter[] {

new RelatedToUrlSearchParameter(null, urls, true),

new PlacementTypeSearchParameter(null,

new SiteConstantsPlacementType[] {SiteConstantsPlacementType.SITE}),

new LanguageTargetSearchParameter(null, new LanguageTarget[] {language}),

new CountryTargetSearchParameter(null, new CountryTarget[] {country})});

selector.setPaging(new Paging(0, 6));

The results you get back may resemble placements like:

made-up-tickets-site.com

made-up-tickets-site.com::Search Results,Top center

made-up-ticket-seller.com

made-up-ticket-seller.com::Homepage,Bottom right

another-made-up-ticket-seller.com

yet-another-made-up-ticket-seller.com

Though you now have a better idea of which placements you would like to pursue, you may still have difficulty ranking your results. We will finally discuss pulling additional attributes to help better evaluate targeting ideas.

Requesting more attributes

The TargetingIdeaService adds new functionality not previously found in v13 to help you better understand your results. For example, you may notice from the results above that "another-made-up-ticket-seller.com" looks interesting, but does not offer much information beyond its URL. To investigate, you can request that a sample URL for each placement be supplied to determine if this is the right website for you. You can do this by adding the SAMPLE_URL attribute to the requestedAttributeTypes parameter:

// PLACEMENT is added to associate with SAMPLE_URL.

selector.setRequestedAttributeTypes(new AttributeType[] {

AttributeType.PLACEMENT, AttributeType.SAMPLE_URL});

When the results are returned, you will then be able to visit each sample URL to investigate the location and quality of placement yourself, something that was not previously possible with v13's SiteSuggestionService. All available attributes are listed in the AttributeType documentation page.

As we've shown in this blog post, there are many new and exciting uses for the TargetingIdeaService. We've included examples of using this service in all of our client libraries to help get you started, so please jump in and let us know of any feedback you may have on our forums.

-- Adam Rogal, AdWords API Team

Discover v2009: Asynchronous requests with the BulkMutateJobService

2009-10-28T09:03:00.000-07:00

Delegation of tasks: we use this concept in our everyday lives when we pay someone to make us coffee, ask a colleague to take care of something while we run to the dentist, or tell our kids or younger siblings to handle a chore. What's common in all these situations? Well, you assign someone a task, possibly consisting of several parts, and then you wait for it to be completed. You can focus on other things while the task is being worked on, but you can still periodically ask what the status is (not too often, or they'll think you're annoying). Eventually they'll tell you it's done, and let you know whether it was successful or not. It's a simple process, and we intuitively know what to expect from it.

Well, you can now delegate complex tasks via the AdWords API! v2009 introduced a unified interface across all services for performing changes: the mutate method. This unification allowed us to develop the BulkMutateJobService, where you can provide a list of mutate operations to be performed for a number of different services, by scheduling a job which gets executed asynchronously. Much like the v13 ReportService, you can then poll for the job status, and once you get back the signal that it's been completed, you can ask for the results.

Let's dive into the details. BulkMutateJobs consist of the following:

BulkMutateRequests: these are the different parts of the job. The first one you submit should include a count of how many parts your job has; you submit one at a time, and once the last one is submitted, the job automatically starts. This helps build very large jobs, by avoiding the sending of a single, gigantic request.
OperationStreams: a BulkMutateRequest contains one or more OperationStreams, which can be executed in parallel (only in certain conditions, namely if their scopes target different campaigns).
Operations: each OperationStream contains a list of Operations, which are performed sequentially.

So to create a job with two parts, you would simply do:

BulkMutateJob job = new BulkMutateJob();
job.setNumRequestParts(2);

and fill in the details for the first part:

BulkMutateRequest part1 = new BulkMutateRequest();
part1.setPartIndex(0);

Then create an operation stream, consisting of several operations (they can even use different operators) and use it in the part:

OperationStream adStream = new OperationStream();
adStream.setScopingEntityId(scopingEntityId);
adStream.setOperations(new Operation[] {
new AdGroupAdOperation(Operator.ADD, null, adGroupAd1, null),
new AdGroupAdOperation(Operator.ADD, null, adGroupAd2, null)});
part1.setOperationStreams(new OperationStream[] {adStream});

Once we're done with that, we can create the JobOperation and submit the first part to the service:

JobOperation jobOperation = new JobOperation();
jobOperation.setOperand(job);
jobOperation.setOperator(Operator.ADD);
job = bulkMutateJobService.mutate(jobOperation);
Long jobId = job.getId();

Submitting the second part is similar, but now we must use the SET operator, since we're adding to an existing job, not creating a new one. Also, we must provide the job ID, so that the system knows which job we're submitting a new part for.

BulkMutateRequest part2 = new BulkMutateRequest();
part2.setPartIndex(1);
// ... OperationStream code goes here ...
job = new BulkMutateJob();
job.setId(jobId); // Here we set the ID to the one we got from
// the response to the first part
job.setRequest(part2);
job = bulkMutateJobService.mutate(new JobOperation(Operator.SET, null, job));

Once all the parts are submitted, the system automatically starts the job. Querying the status is easy, just perform a get with the job ID:

BulkMutateJobSelector selector = new BulkMutateJobSelector();
selector.setJobIds(new long[] {jobId});
BulkMutateJob[] jobs = bulkMutateJobService.get(selector);
job = jobs[0];

Don't query too often, though, or you may run trigger a rate-limiting protection! We recommend 30 seconds as a good value to wait between queries. Once the response comes back with a COMPLETED status, we can retrieve the results for both parts, by setting the resultPartIndex:

selector.setResultPartIndex(0);
jobs = bulkMutateJobService.get(selector);
job = jobs[0];
OperationResult[] operationResults1 =
job.getResult().getOperationStreamResults()[0].getOperationResults();

selector.setResultPartIndex(1);
jobs = bulkMutateJobService.get(selector);
job = jobs[0];
OperationResult[] operationResults2 =
job.getResult().getOperationStreamResults()[0].getOperationResults();

The BulkMutateResult object in the result field of the response includes a list of OperationStreamResults, which themselves are an array of OperationResults. Going through this hierarchy allows you to see which operations were successful and which ones failed, and act accordingly.

Note: If you're looking for a more complete example of using the BulkMutateJobService, please check the examples/demo folder in the client library of your choice. Also check Performing Bulk Jobs with BulkMutateJobService in the API documentation.

With the BulkMutateJobService you can provide as much work as possible to the API in one go and let it do its processing, without worrying about timeouts or broken connections. It won't affect your error handling, either, since the responses detail exactly what happened to all of the operations you performed. It's just an efficient way of getting a lot of work done in a single task. Come in and have a seat, the AdWords API is ready to take your order!

--Sérgio Gomes, AdWords API Team

This is the first of a series of posts on the exciting features of AdWords API v2009. In next week's edition of Discover v2009, we'll tell you all about getting ideas from the new TargetingIdeaService.

Happy Holidays! Enjoy more API units

2009-10-27T08:07:00.000-07:00

We know the holiday season is a busy time for you and often means a number of updates to your campaigns. We'd once again like to help out by providing you with more API units.

Starting now and extending through January 15th of next year, all developers will receive a bonus of 20% more API units at no additional cost.

Developers can purchase API units at the rate of 1250/$0.25, up from 1000/$0.25
Advertisers who are eligible for free API units will receive credit at the rate 300/$ of AdWords spend, up from 250/$ of AdWords spend. They will be credited the holiday bonus based on their spend in previous months

You can view your API usage in your MCC account, by clicking the AdWords API Center link under the My Account tab.

As always, we encourage you to use the API as efficiently as possible. See our blog post on efficiency best practices to learn about ways to get more out of your API units. For more general API best practices, see our previous post dedicated to just that topic. Finally, we encourage developers to take advantage of the efficiencies and cost savings associated with API v2009.

Happy Holidays,
-Shreyas Doshi, Product Manager

AdWords API v200909 now available!

2009-10-22T09:56:00.000-07:00

We're happy to announce the newest version of AdWords API v2009 beta! v200909 introduces several new features to the AdWords API; we've highlighted the main points below. For a complete list of the changes in v200909, please see our release notes.

v200909 Highlights

Asynchronous calls - Asynchronous calls 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’re now able to make another call as soon as the API service confirms that it has received your previous call. No more waiting for the server to complete large requests. V200909 will continue to support Synchronous methods as well.
Keyword and placement ideas - With the new TargetingIdeaService, you'll be able to get keyword and placement ideas through the API, leveraging the functionality of the search-based keyword tool.
Location Extensions preview - Limited location extensions functionality is now available as a preview of the full functionality in development.

Coming soon: Over the next few months, we'll continue to introduce new features and additional AdWords functionality. Upcoming features include ReportService, AccountService and the ability to pre-check for errors.

v13 Sunset in 2010:
With the release of equivalent functionality in v200909, the following v13 services will be sunset on April 22, 2010: CampaignService, AdGroupService, CriterionService, AdService, InfoService, KeywordToolService, SiteSuggestionService.

Given that v2009 introduces new concepts and features, we have extended the sunset period for deprecated services to 6 months. If you haven't already begun migrating your systems to the v2009 API, we strongly encourage you to start right away. The deprecation of remaining v13 services (AccountService, TrafficEstimatorService, and ReportService) and accompanying sunset dates will be announced on a future date.

As with every new version of the AdWords API, we encourage you to review the resources in the Developer's Guide to learn more. Additionally, if you aren't using the AdWords API client libraries yet, this is a good time to check them out as they are designed to work with both v2009 and v13.

Best,

Shreyas Doshi, Product Manager and Adam Wooley, Product Marketing Manager

AdWords Downtime: October 10th, 10am-2pm PDT

2009-10-06T16:27:00.000-07:00

We'll be performing routine system maintenance on Saturday, October 10th 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.

Best,
-Eric Koleda, AdWords API Team

AdWords Downtime: September 12th, 10am-2pm PDT

2009-09-08T15:53:00.000-07:00

We'll be performing routine system maintenance on Saturday, September 12th 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.

Best,

-Eric Koleda, AdWords API Team

AdWords API v2009 (beta) now available to all advertisers

2009-08-26T19:34:00.000-07:00

Today, we are pleased to announce that AdWords API v2009, which we released to a limited whitelist in June, is now available to all API users! Compared to previous versions of the AdWords API, v2009 offers you new features and greater speed at a lower cost.  

Because it offers nearly all of the campaign management functionality you're used to from the AdWords API, along with a new rate sheet representing lower costs, now is a great time to start developing for v2009. Over the next couple of months, we'll be releasing more functionality like asynchronous calls, partial failure acceptance, keyword optimization tools, and reporting.

To get started writing code for v2009, check out the developer documentation on the v2009 homepage. Additionally, we have a v2009 sandbox available to all users for experimentation and testing. The sandbox doesn't charge for API units, and all you need to access it is your current Google Account username and password. Beforehand, read up on sandbox best practices. 

Because there are significant changes between v13 and v2009, we've extended the length of time that we'll support both versions. Our plan is to retire v13 in early 2010, and we'll share exact dates within the next couple of months. In anticipation of retiring v13, we strongly encourage you to begin development for v2009 as soon as possible. We're still working on making v2009 better, so this is also a great opportunity to provide us your early feedback.

Best,

John Fitzpatrick, AdWords API Team

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

2009-08-04T07:54:00.000-07:00

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

Best,
-Eric Koleda, AdWords API Team

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

Update: the client libraries have now been updated to support the latest API version, v200906, in both the sandbox and production environments. An updated version of the PHP library is coming soon.

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