AdWords API v2009 Sandbox Launch

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

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)

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

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

"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